DIGITAL
RESEARCH*
GEM”
Programmer’s Guide
Volume 1: VDI
DIGITAL
RESEARCH
GEM"
Programmer’s Guide
Volume 1: VDI
COPYRIGHT
Copyright © 1985 Digital Research Inc. All rights reserved. No
part of this publication may be reproduced, transmitted,
transcribed, stored in a retrieval system, or translated into any
language or computer language, in any form or by any means,
electronic, mechanical, magnetic, optical, chemical, manual or
otherwise, without the prior written permission of Digital Research
Inc., 60 Garden Court, P.O. Box DRI, Monterey, California 93942.
DISCLAIMER
DIGITAL RESEARCH INC. MAKES NO REPRESENTATIONS OR WARRANTIES WITH
RESPECT TO THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY
IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR
PURPOSE. Further, Digital Research Inc. reserves the right to
revise this publication and to make changes from time to time in the
content hereof without obligation of Digital Research Inc. to notify
any person of such revision or changes.
NOTICE TO USER
From time to time changes are made in the filenames and in the files
actually included on the distribution disk. This manual should not
be construed as a representation or warranty that such files or
facilities exist on the distribution disk or as part of the
materials and programs distributed. Most distribution disks include
a "README.DOC" file. This file explains variations from the manual
which do constitute modification of the manual and the items
included therewith. Be sure to read this file before using the
software.
TRADEMARKS
Digital Research and its logo are registered trademarks of Digital
Research Inc. Concurrent, GEM, GEM Desktop, GEM Draw, Graphics
Environment Manager, and GSX are trademarks of Digital Research Inc.
We Make Computers Work is a service mark of Digital Research Inc.
IBM is a registered trademark of International Business Machines.
Intel is a registered trademark of Intel Corporation. Motorola is a
registered trademark of Motorola Inc. Polaroid is a registered
trademark of Polaroid Corporation.
The GEM™ Programmer's Guide, Volume 1: VDI was printed in the United
States of America.
********************************
* First Edition: April 1985 *
********************************
GEM™
Programmer's Guide
Volume 1: VDI
Release Note 01
The first two pages of this release note contain additions and
changes that you should make to your copy of the GEM Programmer 1 s
Guide, Volume 1: VDI . In addition, please do the following:
• Insert the descriptions of the two new escapes, Escape 24 and
Escape 25, after page 9-29 in your manual.
• Replace Appendix I, "Bit Image File Format," with the new text we
provide.
Page 2-11
Under "Required Functions for Printers," add the following to the
list of Escape values:
24 Inquire printer scan heights
25 Output printer alpha text
Pages 2-14 and 2-15
Under "Required Functions for Metafiles," add the following to the
list of Escape values:
25 Output printer alpha text
Delete the following from the list of opcodes:
117 Inquire character cell width
131 Inquire current face information
Page 6-9
Under "Copy Raster, Transparent," change the first sentence to read
as follows:
This function copies a monochrome rectangular
raster area from a source form (which cannot
be the screen) to a color area.
Page 6-12
Under "Transparent Form," add the following as the third paragraph:
5047-2029-101
GEM Programmer's Guide, Volume Is VDI
Release Note 01
The source and destination forms may be
completely coincident or completely separate,
but they may not partially overlap.
Page 8-3
In the section on the Extended Inquire Function, after intout(18) in
"Output," add and change as follows:
intout(19)— Clipping flag.
0 = Clipping off.
1 = Clipping on.
intout(20-44)- Reserved, contains zeros.
ptsout(0)—
ptsout(l)—
ptsout(2)—
ptsout(3)—
ptsout(4-11)-
Upper left x of the clipping window.
Upper left y of the clipping window.
Lower right x of the clipping window.
Lower right y of the clipping window.
Reserved, contains zeros.
Page 9-2
In Table 9-1, insert the following:
24 INQUIRE PRINTER SCAN HEIGHTS
25 OUTPUT PRINTER ALPHA TEXT
Change the number value immediately following from "24-59" to "26-
59."
Page C-l
Under "Standard Metafile Item Format" in Appendix C, add the
following in the list of function requests, immediately after
"5,23":
5,25 output printer alpha text
Page D-l
The page header should read "Standard Keyboard".
GEM VDI Function Reference Card (at end of manual)
The section reference under Op Code 114 (Fill Rectangle) should be
to Section 4 instead of Section 6.
2
GEM VDI Programmer's Guide
Release Note 01
Copyright© 1985 Digital Research Inc. All rights reserved.
Digital Research and its logo are registered trademarks of Digital
Research Inc. GEM is a trademark of Digital Research Inc. We Make
Computers Work is a service mark of Digital Research Inc.
End of Release Note
GEM VDI Programmer 1 s Guide
Inquire Printer Scan Heights
ESCAPE 24: This escape returns to the calling program
INQUIRE PRINTER information that describes the printing
SCAN HEIGHTS characteristics of the printer. The information
includes the height in pixels of a printer head
pass (in both graphics and alpha modes) and the
number of head passes in a full page.
For devices in which the height of a single
head pass is not a discrete number of pixels,
this escape returns a division factor that
should be factored in. For example, if the
device outputs 12.5 pixels in a single alpha
pass and 4 pixels in a single graphics pass,
this escape returns an alpha scan height of 25,
a graphics scan height of 8, and a division
factor of 2.
Input contrl(O) — Opcode = 5.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 0.
contrl(5) — Function id = 24.
contrl(6) — Device handle.
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 5.
intout(0) — Graphics scan height in
scaled pixels.
intout(l) — Number of graphics head passes
per page.
intout(2) — Alpha scan height in scaled
pixels.
intout(3) — Number of alpha head passes
per page.
intout(4) — Scan height division factor.
C BINDING
Procedure name vq_scan( handle, &g_height, &g_slices,
&a_height, &a_slices, Sefactor );
9-29a
GEM VDI Programmer's Guide
Inquire Printer Scan Heights
Data types
Input arguments
Output arguments
WORD vq_scan()?
WORD handle;
WORD g_height, g_slices, a_height,
factor;
handle = contrl[6]
g_height = intout[0]
g_slices = intout[l]
a_height = intout[2]
a_slices = intout[3]
factor = intout[4]
a slices.
9-29b
GEM VDI Programmer's Guide
Output Printer Alpha Text
ESCAPE 25: OUTPUT This escape is required only for printers.
PRINTER ALPHA TEXT It allows the application to request immediate
output of a string of alpha text to the
printer. The text is output at the current
printer head position. All characters are
output exactly as specified, with the following
exceptions:
• The form-feed character (ADE value 12) has
the same effect as execution of the "Form
Advance" escape (Escape 20).
• The following two-character control sequences
invoke the described functions on the
printer, if they exist. ["(DC2)" refers to
ADE value 18.]
(DC2) 0
(DC2) 1
( DC 2 ) 2
(DC2) 3
( DC 2 ) 4
(DC2) 5
Begin bolding.
End bolding.
Begin italicizing.
End italicizing.
Begin underlining.
End underlining.
Input
contrl(O)
Opcode = 5.
contrl(l)
— Number of input vertices
= 0 .
contrl(3)
contrl(5)
contrl(6)
— Length of intin array =
— Function id = 25.
— Device handle.
n.
intin
Character string as
codes, as described
"Text" in Section 4.
ASCII
under
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure name v_alpha_text( handle, string );
9-29c
GEM VDI Programmer's Guide
Output Printer Alpha Text
Data types
Input arguments
WORD v_alpha_text();
WORD handle;
BYTE stringEn];
handle = contrl[6]
string = intin
Note: Bytes for the string array are mapped
into the eight least significant bits of intin.
The string must be null-terminated.
9-29d
GEM VDI Programmer's Guide
Bit Image File Format
Appendix I
Bit Image File Format
INTRODUCTION A GEM VDI bit image file has the extension .IMG
and contains information used to recreate a
picture from its bit (pixel) image. The file
consists of a header and raw pixel information.
The pixel information can be encoded in a
variety of formats.
HEADER FORMAT The bit image file header consists of a variable
number of 16-bit words in which the high byte
of the word precedes the low byte.
Word Contents
0 image file version number
1 length of the header in words
2 source device bits per pixel
(i.e., number of planes)
3 pattern definition length (bytes)
4 source device pixel width (microns)
5 source device pixel height (microns)
6 scan line width (pixels)
7 number of scan lines
The third word of the header gives the number
of bytes the file uses to describe pattern_run
(see Note 5 below) . The value can range from 1
to 8. (For most bit image captures from screen
devices, the typical value is 2.)
DATA FORMAT The following describes the syntax of the bit
image data:
file ::= <scan_line>* EOF
scan_line :: = [<vert_rep>]<planel>, ... ,
<planeN> (see Note 1)
vert_rep ::= (see Note 2)
planeJ ::= <encoded_data>* (see Note 3)
encoded_data ::= {<solid_run> I
<pattern_run> I <bit_string>}
1-1
GEM VDI Programmer's Guide
Bit Image File Format
solid_run ::= (see Note 4)
pattern_run ::= (see Note 5)
bit_string ::= (see Note 6)
Note 1 Each scan line consists of an optional vertical
replication count followed by encoded data for
each bit plane. The bit planes are specified
in order. The first plane corresponds to the
lowest order bit of a pixel value (see Table 6-
1); the last plane corresponds to the highest
order bit. For example, in a three-plane
system, the red plane is described first,
followed by the green plane, then the blue
plane. Data is always provided for all defined
bit planes.
Note 2 A vertical replication item consists of the
following:
byte contents
0 must be zero
1 must be zero
2 must be 255 (hex FF)
3 count
The count specified in the last byte of the
vertical replication item indicates how many
identical scan lines are defined by the
scan line item.
Note 3 The number of pixels described for each bit
plane of a scan line is not necessarily the
scan-line width specified in the file header.
Because the data is encoded in byte-wide
packets (packets of eight pixels), the number
of pixels actually described is always a
multiple of eight and is never more than seven
pixels wider than the scan-line width.
1-2
GEM VDI Programmer's Guide
Bit Image File Format
Note 4 A solid_run item contains a single byte that
describes a state (SET or NOT SET) and the
number of bytes for which that state is true.
The high-order bit defines the state (1 = SET,
0 = NOT SET), and the low-order seven bits
define the run length.
For example, in a three-plane system, a stream
of 24 red pixels can be encoded as a solid run
of Is three bytes long in the red plane (hex
83). In the same system, the green and blue
planes would each have a solid run of Os three
bytes long (hex 03).
Note 5 A pattern_run item describes a set of pattern
bytes and the number of times the pattern bytes
should be repeated. The number of bytes in a
pattern is defined in the bit image file
header; typically, it is two for a screen
device image. The pattern__run item is defined
as follows:
byte contents
0 must be zero
1 run length
2 first byte of pattern
n last byte of pattern
For example, a three-plane system could have a
stream of 48 pixels alternating red and blue.
If the pattern width item in the image-file
header is set to two, the red and blue bit
planes can be encoded in the following manner:
• red bit plane: a three-byte pattern run with
the pattern bytes set to hex AAAA
• blue bit plane: a three-byte pattern run with
the pattern bytes set to hex 5555
The green bit plane in this example is a six-
byte solid run of Os (hex 06).
1-3
GEM VDI Programmer's Guide
Bit Image File Format
Note 6 If a stream of pixels for a given plane cannot
be encoded efficiently as a solid run or
pattern run, it must be encoded as a bit
string. The bit_string item is defined as
follows:
byte contents
0 must be hex 80
1 byte count
2 first byte of bit string
n last byte of bit string
End of Appendix I
1-4
Foreword
OBJECTIVE
This guide describes the features and operation
of the Graphics Environment Manager™ (GEM™ )
Virtual Device Interface (VDI), the successor
to the Digital Research® Graphics System
Extension (GSX™ ). You can write graphics
applications using GEM VDI capabilities.
AUDIENCE
This guide is intended for microcomputer
application programmers with operating system
and graphics programming experience.
ORGANIZATION
This guide contains nine sections, nine
appendixes, a glossary, and an index. The
detachable reference card at the end of this
guide lists the GEM VDI functions by opcode
number and gives their respective C binding
procedure names. It also lists the section of
this guide in which each function is discussed.
Section 1 introduces GEM VDI. It describes the
GEM VDI architecture, including the Graphics
Device Operating System (GDOS) and the device
drivers.
Section 2 describes GEM VDI operating
procedures and how to integrate application
programs with GEM VDI.
Section 3 describes the control functions,
which initialize the graphics workstation and
set defaults for use with the application.
Section 4 describes the output functions, which
cause graphics primitives to be displayed on a
graphics output device (a screen or plotter,
for example).
Section 5 describes the attribute functions,
which determine qualities of all subsequent
output primitives, such as color and style.
Section 6 describes the raster functions, which
perform logic operations on raster areas
(rectangular blocks of bits in memory or pixels
on physical devices).
i ii
Section 7 describes the input functions. Which
allow the user to interact with the application
program.
Section 8 describes the inquire functions,
which return the current settings for device¬
specific attributes, such as the number of text
styles supported.
Section 9 describes the escape functions, which
allow the application program to access special
device capabilities.
Appendix A lists and describes the GEM VDI
error messages.
Appendix B explains the ASSIGN.SYS file
contents, which include information the GDOS
uses to identify the output device.
Appendix C lists and describes the GEM VDI
metafile format.
Appendix D defines the GEM VDI standard
keyboard.
Appendix E describes the mapping of GEM VDI to
specific microprocessors and the calling
procedures needed to perform that mapping.
Appendix F includes the system fonts.
Appendix G describes the font file format.
Appendix H describes the reserved metafile sub¬
opcodes.
Appendix I describes the bit image file format.
Table of Contents
1 Overview
Introduction. 1-1
Features. 1-1
Enhancements . 1-1
Architecture . 1-2
Graphics Device Operating System (GDOS) . 1-2
Graphics Device Drivers .... . 1-3
Device Types . 1-3
Metafiles. 1-3
Multiple Workstations . 1-4
Device Handles . 1-4
ASSIGN. SYS. 1-4
Application Programs . 1-5
Virtual Device Interface . 1-5
Transforming Points . 1-6
Transformation Mode. 1-6
Normalized Device Coordinates . 1-6
Raster Coordinates . 1-7
2 Writing a Graphics Application
Introduction . 2-1
GEM VDI Distribution Files. 2-1
Writing the Program. 2-1
GEM VDI Functions. 2-9
Opcodes. 2-9
Required Functions for Screens . 2-9
Required Functions for Printers . 2-11
Required Functions for Plotters . 2-13
Required Functions for Metafiles . 2-14
Available Opcodes . 2-16
Format. .2-16
Input Parameters.2-16
Output Parameters . 2-17
v
Table of Contents (continued)
Calling Conventions . 2-17
Registers and Interrupts . 2-18
Running Graphics Applications Under GEM VDI . 2-18
Enabling Graphics . 2-19
Disabling Graphics . 2-20
Determining Memory Requirements . 2-20
Debugging Graphics Applications under GEM VDI . 2-20
3 Control Functions
Introduction .. 3-1
Open workstation. 3-1
Close Workstation. 3-9
Open Virtual Screen Workstation . 3-10
Close Virtual Screen Workstation . 3-13
Clear Workstation.3-14
Update Workstation . 3-15
Load Fonts.3-16
Unload Fonts . 3-17
Set Clipping Rectangle . 3-19
4 Output Functions
Introduction . 4-1
Polyline. 4-1
Polymarker. 4-4
Text. 4-6
Table of Contents (continued)
Filled Area. 4-8
Cell Array.4-11
Contour Fill .4-13
Fill Rectangle ..... . 4-14
Generalized Drawing Primitive (GDP) . 4-15
Bar.4-18
Arc & Pie.4-19
Circle.4-21
Elliptical Arc and Pie.4-22
Ellipse.4-24
Rounded and Filled Rounded Rectangle . 4-25
Justified Graphics Text . 4-27
5 Attribute Functions
Introduction . 5-1
Set Writing Mode. 5-1
Replace. 5-2
Transparent. 5-2
XOR. 5-2
Reverse Transparent . 5-3
Set Color Representation . 5-4
Set Polyline Line Type. 5-6
Set User-defined Line Style Pattern . 5-8
Set Polyline Line Width. 5-9
Set Polyline Color Index . 5-11
Set Polyline End Styles.5-12
Set Polymarker Type.5-14
vii
Table of Contents (continued)
Set Polymarker Height . 5-16
Set Polymarker Color Index . 5-17
Set Character Height, Absolute Mode . 5-18
Set Character Cell Height, Points Mode.5-20
Set Character Baseline Vector . 5-22
Set Text Face.5-24
Set Graphic Text Color Index.5-26
Set Graphic Text Special Effects . 5-27
Set Graphic Text Alignment.5-30
Set Fill Interior Style.5-32
Set Fill Style Index.5-33
Set Fill Color Index.5-35
Set Fill Perimeter Visibility.5-36
Set User-defined Fill Pattern.5-37
6 Raster Operations
Introduction . 6-1
Memory Form Definition Block . 6-1
Raster Area Formats. 6-2
Coordinate Systems . 6-4
Logic Operations. 6-6
Copy Raster, Opaque. 6-7
Copy Raster, Transparent . 6-9
Replace Mode. 6-9
Transparent Mode. 6-9
XOR Mode. 6-9
Reverse Transparent Mode . 6-10
Table of Contents (continued)
Transform Form . ..... 6-12
Get Pixel.6-13
7 Input Functions
Introduction . 7-1
Set Input Mode. 7-1
Input Locator, Request Mode. 7-3
Input Locator, Sample Mode. 7-6
Input Valuator, Request Mode. 7-9
Input Valuator, Sample Mode.7-11
Input Choice, Request Mode.7-13
Input Choice, Sample Mode.7-14
Input String, Request Mode.7-15
Input String, Sample Mode.7-17
Set Mouse Form.7-19
Exchange Timer Interrupt Vector . 7-21
Show Cursor. 7-23
Hide Cursor.7-25
Sample Mouse Button State . 7-26
Exchange Button Change Vector . 7-27
Exchange Mouse Movement Vector . 7-29
Exchange Cursor Change Vector . 7-31
Sample Keyboard State Information . 7-33
8 Inquire Functions
Introduction . 8-1
Extended Inquire . 8-1
ix
Table of Contents (continued)
Inquire Color Representation . 8-5
Inquire Current Polyline Attributes . 8-7
Inquire Current Polymarker Attributes . 8-9
Inquire Current Fill Area Attributes . 8-11
Inquire Current Graphic Text Attributes . 8-13
Inquire Text Extent.8-15
Inquire Character Cell Width . 8-17
Inquire Face Name and Index.8-19
Inquire Current Face Information . 8-21
Inquire Cell Array.8-23
Inquire Input Mode. 8-25
9 Escapes
Escape. 9-1
ESCAPE 1: Inquire Addressable Character Cells . 9-4
ESCAPE 2: Exit Alpha Mode. 9-5
ESCAPE 3: Enter Alpha Mode. 9-6
ESCAPE 4: Alpha Cursor Up. 9-7
ESCAPE 5: Alpha Cursor Down. 9-8
ESCAPE 6: Alpha Cursor Right . . 9-9
ESCAPE 7: Alpha Cursor Left.9-10
ESCAPE 8: Home Alpha Cursor.9-11
ESCAPE 9: Erase to End of Alpha Screen.9-12
ESCAPE 10: Erase to End of Alpha Text Line.9-13
ESCAPE 11: Direct Alpha Cursor Address . 9-14
ESCAPE 12: Output Cursor Addressable Alpha Text .... 9-15
ESCAPE 13: Reverse Video On.9-16
x
Table of Contents (continued)
ESCAPE 14: Reverse Video Off.9-17
ESCAPE 15: Inquire Current Alpha Cursor Address .... 9-18
ESCAPE 16: Inquire Tablet Status . 9-19
ESCAPE 17: Hard Copy.9-20
ESCAPE 18: Place Graphic Cursor at Location . 9-21
ESCAPE 19: Remove Last Graphic Cursor . 9-22
ESCAPE 20: Form Advance.9-23
ESCAPE 21: Output Window . 9-24
ESCAPE 22: Clear Display List.9-26
ESCAPE 23: Output Bit Image File.9-27
ESCAPE 60: Select Palette . 9-30
Polaroid Palette . 9-31
Palette Driver . 9-31
Error Messages.9-31
ESCAPE 91: Inquire Palette Film Types . 9-32
ESCAPE 92: Inquire Palette Driver State . 9-33
ESCAPE 93: Set Palette Driver State . 9-35
ESCAPE 94; Save Palette Driver State . 9-37
ESCAPE 95: Suppress Palette Messages . 9-38
ESCAPE 96: Palette Error Inquire . 9-39
ESCAPE 98: Update Metafile Extents . 9-41
ESCAPE 99: Write Metafile Item.9-43
ESCAPE 100: Change GEM VDI Filename.9-44
xi
Table of Contents (continued)
Appendixes
A GEM VDI Error Messages. A-l
B ASSIGN.SYS File
Requirements . B-l
Device Id Numbers. B-l
Device Driver Filename . B-l
Format. B-l
Sample ASSIGN.SYS . B-2
C GEM VDI Metafile Format
Introduction . C-l
Standard Metafile Item Format . C-l
Nonstandard Metafile Items . ... C-2
1 open workstation . C-2
2 close workstation . C-4
Special Metafile Escapes . C-4
5, 98 update metafile extents . C-4
5, 99 write metafile item escape. C-4
5, 100 change GEM VDI filename escape. C-4
Inquiry Functions . C-5
D Standard Keyboard . D-l
E Processor-Specific Data
8086-Specific Data .. E-l
68000-Specific Data. E-3
F Character Sets. F-l
xii
Table of Contents (continued)
G Font Format
Introduction . G-l
Font Data. G-l
Font Header. G-l
Character Offset Table ... . G-4
Horizontal Offset Table . G-4
H Reserved Metafile Sub-opcodes
Metafile Sub-opcodes for Use with GEM Output. H-l
Physical Page Size. H-l
Coordinate Window . H-2
Metafile Sub-opcodes for Use with GEM Draw. H-3
Start Group. H-3
End Group. H-4
Set No Line Style. H-4
Set Attribute Shadow On. H-5
Set Attribute Shadow Off. H-6
Start Draw Area Type Primitive. H-6
End Draw Area Type Primitive. H-7
I Bit Image File Format
Introduction . 1-1
Header Format . 1-1
Data Format. 1-1
Run-length Encoding . 1-2
Extended Run-length Encoding . 1-2
Raster Encoding. 1-3
Raster-run Encoding . 1-3
xiii
Table of Contents (continued)
Glossary . 1
Tables
1- 1. Device Identification Numbers . 1-5
2- 1. Parameter Block Contents . 2-18
3- 1. Monochrome Screens . 3-6
3-2. Monochrome Printer/Plotters . 3-6
3-3. Color Screens. 3-6
3-4. Default Values. 3-7
5-1. Writing Modes. 5-1
5-2. Terms. 5-2
5- 3. Attribute Bit Mapping.5-27
6- 1. Pixel Value to Color Index Mapping for
8-color Screens . 6-3
6-2. Pixel Value to Color Index Mapping for
16-color Screens . 6-4
6- 3. Raster Operation Logic Operations . 6-6
7- 1. Sample Mode Status Returned . 7-7
8- 1. Face Names and Styles.8-19
9- 1. Escape Function Indentifiers . 9-1
B-l. Device id Numbers. B-l
D-l. GEM VDI Standard Keyboard Assignments. D-l
G-l. Font Header Format. G-2
xiv
Table of Contents (continued)
Figures
1- 1. Transformation Modes . 1-8
2- 1. Output from the Sample Program. 2-2
4-1. First Point for Wide Lines. 4-1
4- 2. Angle Specification . 4-15
5- 1. Character Cell Definition.5-20
5-2. Angle Specification . 5-22
5-3. Graphic Text Special Effects . 5-28
5-4. Graphic Text Alignment.5-30
5- 5. Fill Styles and Indices.5-33
6- 1. Memory Form Definition Block . 6-2
6-2. Standard Forms. 6-5
6-3. Sample Single Plane Memory Form . 6-5
8-1. Inquire Text Extent Function . 8-15
8-2. Character Cell Definition.8-17
8-3. Right and Left Offset.8-21
B—1. ASSIGN.SYS File Format. B-l
F-l. GEM VDI USASCII Character. Set. F-2
F-2. GEM VDI International Character Set Extension .... F-3
Listings
2-1. Sample Program. 2-2
2-2. Sample Assembly Language Application . 2-3
xv
Section 1
Overview
INTRODUCTION The GEM VDI provides a device-independent
environment in which you can write graphics
applications. This section describes GEM VDI
and its architecture. Subsequent sections
describe writing an application and all the GEM
VDI functions.
FEATURES The following features of GEM VDI make it
possible for you to write graphics applications
that run under several microcomputer operating
systems:
• GEM VDI provides a common graphics
programming interface that is compatible with
the most widely used operating systems, thus
making it easy to port many programs.
• GEM VDI provides a device-independent
software interface for your application
programs. You do not need to rewrite
applications for use with different output
devices such as screens, printers, and
plotters. GEM VDI handles device differences
and makes it possible for you to send
information to the devices through the
application program as if the devices were
the same. GEM VDI handles graphics requests
and supplies the right driver to run the
specific device.
ENHANCEMENTS GEM VDI includes enhancements to GSX functions
and now includes the following capabilities:
• raster functions—functions that affect
raster areas, which are rectangular blocks of
pixels on physical devices or rectangular
blocks of bits in memory
• faces—letter styles stored in dynamically
loadable files
1-1
GEM VDI Programmer’s Guide
Architecture
ARCHITECTURE
Graphics
Device Operating
System (GDOS)
GEM VDI provides graphics primitives for
implementing graphics applications with reduced
programming effort. Application programs
interface to GEM VDI through a standard calling
sequence. Drivers for specific graphics
devices translate the standard GEM VDI calls to
the unique characteristics of each device. In
this way, GEM VDI provides device independence.
GEM VDI is composed of two components:
• Graphics Device Operating System (GDOS)
• device drivers and face files
The GDOS contains the device-independent
graphics functions, while the device drivers
and face files contain the device-dependent
code.
GEM VDI is designed in this way to make the
principal parts of the GDOS transportable to
different hardware configurations. This design
also allows applications to run independently
of the specific devices connected to the
system.
The Graphics Device Operating System (GDOS)
contains the basic host and device¬
independent graphics functions that can be
called by your application program. GDOS
provides a standard graphics interface that is
constant regardless of specific devices or host
hardware, just as the disk operating system
standardizes disk interfaces. Your application
program accesses the GDOS in much the same way
that it accesses the operating system.
The GDOS performs coordinate scaling so that
your application can specify points in a
normalized space. It uses device-specific
information to transform (map) the coordinates
into the corresponding values for a particular
graphics device.
An application can also specify points in
raster coordinate space, in which case no
transformation occurs.
1-2
GEM VDI Programmer's Guide
Architecture
Graphics The graphics device drivers are similar to
Device Drivers any I/O system. They contain the device¬
specific code required to interface your
particular graphics devices to the GDOS. The
device drivers communicate directly with the
graphics devices. GEM VDI requires a unique
device driver for each graphics device in a
system.
A single program can use several graphics
devices? the GDOS loads only the appropriate
device driver file into memory. By referring
to devices with a device identification number,
an application program can send graphics
information to any one of several memory-
resident device drivers.
The device driver outputs the GEM VDI graphics
primitives according to the inherent
capabilities of a particular graphics device.
In some cases, a device driver emulates
standard capabilities not provided by the
graphics device hardware. For example, some
devices require that dashed lines be simulated
by a series of short vectors generated in the
device driver.
The GEM VDI package contains drivers for many
of the most popular microcomputer-related
graphics devices.
DEVICE TYPES You can write a GEM VDI-based graphics
application for a variety of devices including
screens, plotters, printers, and special
cameras.
Metafiles A metafile is the stored generic form of a
picture file. Any application can create a GEM
VDI metafile that can later be called into
another graphics application. The metafile
driver stores a description of a picture in a
data file. These files can later be sent to
any device or used to exchange a picture
between two applications.
1-3
GEM VDI Programmer's Guide
Device Types
When GEM VDI creates a metafile, it provides
the ideal device. Raster Coordinate (RC) and
Normalized Device Coordinate (NDC) space are
the same (0 to 32767). No transform is
applied. Refer to "Transforming Points" later
in this section for more information on the
coordinate spaces.
Refer to Appendix C for information about the
file format for metafiles.
Multiple
Workstations
The application program specifies the
graphics function to be performed by a device
driver with an operation code (opcode) in the
control array. "Opcodes" in Section 2
describes the opcodes.
Because multiple workstations can be open at
the same time, each GEM VDI function must be
provided with a unique reference to the desired
device. This identification is referred to as
the device handle.
Device Handles
The GDOS assigns the device handle when the Open
Workstation function is called by the
application program. The Open Workstation call
returns the device handle in the array element
contrl(6). All subsequent GEM VDI calls need
to supply the device handle as an input in
element contrl(6).
ASSIGN.SYS
The ASSIGN.SYS file is a text file, and can be
created or edited using any text editor. The
file lists the device driver filenames and face
filenames, their device numbers, and device¬
specific information. The device numbers are
assigned according to their type. Refer to
Table 1-1 for device numbers.
1-4
GEM VDI Programmer's Guide
Device Types
Table 1-1. Device Identification Numbers
Device Type
Device Number
Screen
1-10
Plotter
11-20
Printer
21-30
Metafile
31-40
Camera
41-50
Tablet
51-60
APPLICATION With appropriate calls to the GDOS, you can
PROGRAMS write application programs in assembly language
or in a high-level language that supports the
GEM VDI calling conventions. You can compile
or assemble and link programs containing GEM
VDI calls in the normal manner. Refer to
Section 2 for more information about writing
graphics application programs.
VIRTUAL DEVICE This guide contains the specification of the
INTERFACE GEM Virtual Device Interface (VDI) and defines
how applications interface to GEM VDI. The GEM
VDI specifies the calling sequence to access
device driver functions as well as the
necessary calling parameters. Refer to
Appendix E for the main entry into the VDI for
your operating system.
The main entry point into the VDI is a single
subroutine with five arguments, in the form of
five arrays:
• control array
• array of input parameters
• array of input point coordinates
• array of output parameters
• array of output point coordinates
1-5
GEM VDI Programmer's Guide
Virtual Device Interface
All array elements are of type INTEGER (2
bytes). All arrays are zero-based; that is,
the double-word address of the Parameter Block
(PB) points to the first element of the control
array, contrl(O). The content of the input and
output parameter arrays depends on the opcode.
Refer to Section 2 for more information about
writing graphics applications.
TRANSFORMING All computer graphics are displayed using a
POINTS coordinate system. GEM VDI makes sure the
coordinate system of one device matches the
coordinate system of another. For example,
with GEM VDI, the application program produces
the same graphics image on a printer as on a
screen. The linetypes and fill styles are the
same in Normalized Device Coordinates (NDC),
which are described below. Character sizes are
different. The same number of characters are
displayed per line, but a printer's line length
is generally greater than a screen's.
Transformation The application program can address the
Mode display surface using one of two coordinate
systems:
• Normalized Device Coordinates (NDC)
• Raster Coordinates (RC)
The transformation mode, specified at Open
Workstation, determines which coordinate system
is used.
Normalized Device Normalized Device Coordinates (NDC) address
Coordinates the graphics display independent of the device
coordinate size. These units are then mapped
to Raster Coordinates by the GDOS. The
transformation mode set at Open Workstation
determines whether the GDOS maps from NDC units
to the Raster Coordinates.
1-6
GEM VDI Programmer's Guide
Transforming Points
The full scale of NDC space (0-32767) is mapped
to the full dimensions of the device on both
axes. On a nonsquare display with square
pixels, a different scale factor is applied to
each axis with this transformation mode.
NDC space has its origin at the lower left
corner, and its (xmax,ymax) point at the upper
right corner. This space is in the first
quadrant of the Cartesian coordinate system.
When transforming from NDC to Raster
Coordinates (RC), the GDOS assumes a raster
coordinate at the bottom left edge of a pixel.
You should compensate for a boundary condition
created at the top edge of NDC space.
This problem is best illustrated with an
example. Given the display of Figure 1-1 in
Transformation Mode 0, the NDC point
(32767,32767) maps to the point (0,200) in RCs.
But because pixels are addressed at their lower
left corner, the NDC point (32766,32766) maps
to the point (1,199) in RCs. The application
programmer should correct for this boundary
error by adding half of the NDC height and
width into the coordinate transform to ensure
that any roundoff error in the application-
world-to-NDC transform does not cause the wrong
pixel to be addressed.
Raster Coordinates Raster Coordinates (RC) are actual device units
(for example, rasters for screens or steps for
plotters and printers). Unlike NDCs, RCs have
their origin at the upper left corner, and the
(xmax,ymax) point at the bottom right pixel of
the space. Refer to Figure 1-1 for an
illustration of this concept.
No transformation occurs when the RC system is
in effect. The application needs to adjust its
transform based on the aspect ratio of pixels
on the screen. The raster coordinate system
saves the overhead of the GDOS having to
perform a transformation on every point.
1-7
GEM VDI Programmer's Guide
Transforming Points
(32767,32767)
Mode 0
Full NDC mapped to full RC space
Mode 2
Application works in RC space
(640,200)
Figure 1-1. Transformation Modes
End of Section 1
1-8
Section 2
Writing a Graphics Application
INTRODUCTION This section explains how to use GEM VDI in your
graphics applications.
GEM VDI When you receive your GEM VDI distribution
DISTRIBUTION disks, first duplicate them and then store
FILES them in a safe place. Then, using the duplicate
disks, transfer the GEM VDI files to working
system disks. Always use the duplicate disks
to generate any new copies of GEM VDI. Do not
use the distribution disks for routine
operations.
WRITING THE You can write your graphics application in
PROGRAM one of two ways:
• using assembly language
• using high-level language bindings (C
language bindings are provided.)
The first method addresses functions by their
opcode numbers, the second by procedure name.
The C Language bindings provided for each
function allow for portability across
implementations. In the C bindings, which
appear with each function in sections 3 through
9, WORD declares a 16-bit integer type; BYTE
declares an 8-bit integer type.
The following figure is produced by the sample
C language graphics application in Listing 2-1
that follows the figure. Listing 2-2 is a
sample assembly language graphics program.
2-1
GEM Programmer's Guide
Writing the Program
Figure 2-1. Output from the Sample Program
Listing 2-1. Sample Program
/* The following globals must be declared to satisfy the */
/* external references from the C binding routine. */
int contrl[12];
int intin[128];
int ptsin[128];
int intout[128];
int ptsout[128];
main ( )
int handle, i, pxyarray[12], work_in[ll], work_out[57];
int x,y, term;
/* Open the workstation. */
work_in[0] = 1;
for (i = 1; i < 10; i++)
work_in[i] = 1;
work_in[10] =0; /* use NDC coordinates */
v_opnwk(work_in, Shandle, work_out);
/* Output a polyline. */
pxyarray[0] = 12000; /* vertices... */
pxyarray[1] = 12000;
pxyarray[2] = 12000;
pxyarray[3] = 20000;
pxyarray[4] = 14000;
pxyarray[5] = 21000;
pxyarray[6] = 16000;
pxyarray[7] = 20000;
pxyarray[8] = 16000;
pxyarray [9] = 12000;
pxyarray[10] = 12000;
pxyarraytll] = 12000;
v_pline(handle, 6, pxyarray); /* output polyline */
2-2
GEM Programmer's Guide
Writing the Program
Listing 2-1. (continued)
/* Pause for viewing. */
vrq_locator(handle, 16000, 16000, &x, &y, sterm)j
/* Close the workstation. */
v_clswk(handle);
} /* End "main". */
Listing 2-2. Sample Assembly Language Application
.*******************************************************************
; *
; Sample Assembly language program to interface with GEM VDI *
; *
; To open the workstation, draw a border, and say hello world *
7 *
.*******************************************************************
false equ 0
true equ not false
dly equ 05FH ; for delay process, 0FFFF is max delay possible
W_0 equ word ptr 0
W_1 equ word ptr 2
W_2 equ word ptr 4
W_3 equ word ptr 6
W_4 equ word ptr 8
W_5 equ word ptr 10
W_6 equ word ptr 12
W_7 equ word ptr 14
W_8 equ word ptr 16
W_9 equ word ptr 18
W_10 equ word ptr 20
W_ll equ word ptr 22
W_12 equ word ptr 24
W_13 equ word ptr 26
W_14 equ word ptr 28
W_15 equ word ptr 30
w_16 equ word ptr 32
W_17 equ word ptr 34
W_18 equ word ptr 36
W_19 equ word ptr 38
W_20 equ word ptr 40
2-3
GEM Programmer's Guide
Writing the Program
Listing 2-2. (continued)
parameter array sizes *
****************************************************************
CONTRL_SIZE equ 11
INTIN_SIZE equ 128
PTSIN_SIZE equ 256
INT0UTJ3IZE equ 128
PTS0UTJ5IZE equ 12
.*****************************************************************
; start the main body of the code *
.*****************************************************************
cseg
?
; declare these publics so that the labels appear in the symbol file
; useful for debugging purposes
public entry
public opnwk
public border
public announce
public delay
public clswk
public gemvdi
entry:
; set up the stack as required for all main assembly language programs
pushf
mov cx,sp
mov bx,ss
cli
mov ax,seg mystack
mov ss,ax
mov sp, offset mystack_top
sti
popf
; set up the pointers to the gemvdi arrays (contrl_ptr = offset:segment of CONTRL)
; this example does it when the code is loaded
?
opnwk:
; load the CONTRL and INTIN arrays for an openworkstation call
mov CONTRL + W_0,1 ; opcode for openworkstation
mov CONTRL + W_1,0 ; 0 ptsin values
mov CONTRL + W_3,11 j 11 intin values
2-4
GEM Programmer's Guide
Writing the Program
Listing 2-2. (continued)
mov INTIN + W_0,1
mov INTIN + W_l,l
mov INTIN + W_2,1
mov INTIN + W_3,l
mov INTIN + W_4,1
mov INTIN + W_5,l
mov INTIN + W_6,l
mov INTIN + W_7,l
mov INTIN + W_8,1
mov INTIN + W_9,1
mov INTIN + W_10,2
; call gemvdi
call gemvdi
; save the handle returned by openworkstation
mov ax,CONTRL + W_6 ; this is the handle returned by open and needed
mov handle,ax ; by all other calls to the open workstation
; copy INTOUT and PTSOUT into open_device, my local copy of the Device Table
cld ; autoincrement the si and di registers
push ds ; prepare es:di to move words to open_device
pop es
lea di,open_device
mov cx,45 ; prepare to load 45 words from INTOUT
lea si,INTOUT
rep movsw
mov cx,12 ; prepare to load 12 words from PTSOUT
lea si,PTSOUT
rep movsw
border:
; load CONTRL and INTIN arrays to draw a border and a diagonal
mov CONTRL + w_0,6 ; opcode for polyline
mov ax,handle ? put the handle into CONTRL
mov CONTRL + W_6,ax
mov CONTRL + W_1,6 ; it takes 5 points to enclose the border of the device
; and one more for the diagonal
mov CONTRL + W_3,0 ; nothing for INTIN
mov PTSIN + W_0,0 ; point 1 is at (0,0)
mov PTSIN + W_1,0
mov ax,open_device + W_0 ;the max x resolution is the first entry of open_device
mov PTSIN + W_2,ax ; point 2 is at (xresmx,0)
mov PTSIN + w_3,0
mov bx,open_device + W_1 ;the max x resolution is the first entry of open_device
mov PTSIN + W_4,ax ; point 3 is at (xresmx,yresmx)
mov PTSIN + W_5,bx
mov PTSIN + W_6,0 ; point 4 is at (0,yresmx)
mov PTSIN + W_7,bx
device ia = i
linetype
line color
marker type
marker color
font
text color
fill interior style
fill style index
fill color index
transformation flag = RC system
2-5
GEM Programmer's Guide
Writing the Program
Listing 2-2. (continued)
mov PTSIN + W_8,0 ; point 5 is at (0,0)
mov PTSIN + W_9,0
mov PTSIN + w_10,ax ; point 6 is at (xresmx,yresmx)
mov PTSIN + w_ll,bx
; call gemvdi
call gemvdi
announce:
; load CONTRL and INTIN arrays to write "hello world" in the default
; system face and font, with default alignment, at the center of the device
mov CONTRL + W_0,8 ; opcode for text
mov ax,handle ; put the handle into CONTRL
mov CONTRL + W_6,ax
mov CONTRL + W_1,1 ; text location vertice
mov CONTRL + W_3,length anncmnt ; length of the text string to be sent
mov ax,open_device + W_0 ; put the max x resolution in ax
shr ax,l ; divide the max x resolution by two
mov bx,open_device + W_1 ; put the max y resolution in bx
shr bx,l ; divide the max y resolution by two
mov PTSIN + w_0,ax ; put the center point coordinate in PTSIN
mov PTSIN + W_l,bx
cld ; autoincrement the si and di registers
mov cx,length anncmnt ; prepare to move the announcment string into INTIN
lea si,anncmnt
push ds
pop es
lea di,INTIN
xor ah,ah ; make sure the high byte is clear
internallooplj
lodsb ; transfer a byte from the source, to the accumulator
stosw ; store the accumulator in the destination
loop internalloopl ; do this operation for each byte in the source
; call gemvdi
call gemvdi
delay:
; delay for viewing
mov cx,dly
delayloop3:
push cx
mov cx,dly
delayloop2:
push cx
mov cx,dly
delayloopl:
xchg ax,bx
loop delayloopl
2-6
GEM Programmer’s Guide
Writing the Program
Listing 2-2. (continued)
pop cx
loop delayloop2
pop cx
loop delayloop3
clswk:
; load CONTRL array to closeworkstation call
mov CONTRL + W_0,2 ; opcode for close workstation
mov ax,handle ; put the handle into CONTRL
mov CONTRL + W_6,ax
mov CONTRL + W_1,0 ; no input vertices
mov CONTRL + W_3,0 ; no INTIN values
; call gemvdi
call gemvdi
; done with the main program, return to the operating system
mov ax,4c00h
xor cx,cx
xor dx,dx
int 21h ; this is where control returns to the o.s.
•**********************************************************************
; the gemvdi subroutine call for the main program *
***********************************************************************
GDOS EQU OEFH ; interrupt the os with this interrupt vector for
; calls to GEM VDI
gemvdi:
mov ax, seg contrl_ptr
mov ds,ax
Lea dx, contrl_ptr ; DX points to GEM VDI parameter array address
Mov cx, 0473h ; GEM VDI function number into CX
Int GDOS ; Call GDOS
; end of the code segment of the sample program
t
; begin the data segment for the sample program
DATA dseg PUBLIC word
DGROUP GROUP DATA
t
; declare these publics so that the labels appear in the symbol file
; useful for debugging purposes
public CONTRL
public INTIN
public PTSIN
public INTOUT
2-7
GEM Programmer's Guide
Writing the Program
Listing 2-2. (continued)
public PTSOUT
public contrl_ptr
public intin_ptr
public ptsin_ptr
public intout_ptr
public ptsout_ptr
public handle
public open_device
CONTRL rw CONTRL_SIZE
INTIN rw INTIN_SIZE
PTSIN rw PTSIN_SIZE
INTOUT rw INTOUT_SIZE
PTSOUT rw PTSOUT SIZE
contrl_ptr dw offset CONTRL
dw seg CONTRL
intin_ptr dw offset INTIN
dw seg INTIN
ptsin_ptr dw offset PTSIN
dw seg PTSIN
intout_ptr dw offset INTOUT
dw seg INTOUT
ptsout_ptr dw offset PTSOUT
dw seg PTSOUT
these are fixed when the program is loaded
to be double word pointers to the arrays
this is the parameter block to which ds:dx
points when GEM VDI is called
handle dw 0
open_device rw INTOUT_SIZE + PTSOUTSIZE
anncmnt db 'Sample Assembly Language Program'
; end the data segment for the sample program
;begin the stack segment for the sample program
STACK sseg PUBLIC word
SGROUP GROUP STACK
? as stated in the VDI programmers guide, the caller must supply at
; least 128 words of stack for the GEM VDI openworkstation call.
; the calls to the gemvdi subroutine in the code above require at most
; 6 points, or 12 words words of stack.
; assume an o.s overhead of 128 bytes.
; this means a minimum of 264 words on the stack
mystack rw 264
mystack_top rw 0 ;push decrements before store
; end the stack segment for the sample program
2-8
GEM Programmer's Guide
Writing the Program
Listing 2-2. (continued)
; end the sample program. Indicate this is main body and code starts at entry
end entry
GEM VDI Functions The functions are grouped by type, output, and
so on. Each device type requires certain
functions, lists of which follow.
Opcodes Opcodes are numbers assigned to each GEM VDI
function. The device drivers recognize all
opcodes, whether or not they produce any
action. If an opcode is out of range, the
driver performs no action.
Required Functions Screens require the following functions and
for Screens subfunctions:
Opcode Definition
1 Open workstation
2 Close workstation
3 Clear workstation
4 Update workstation
5 Escape
Id Definition
1 Inquire addressable character
cells
2 Exit alpha mode
3 Enter alpha mode
4 Cursor up
5 Cursor down
6 Cursor right
7 Cursor left
8 Home cursor
9 Erase to end of screen
2-9
GEM VDI Programmer's Guide
Writing the Program
10 Erase to end of line
11 Direct cursor address
12 Output cursor addressable text
15 Inquire current alpha cursor
address
18 Place graphic cursor
19 Remove last graphic cursor
6 Polyline
7 Polymarker
8 Text
9 Filled area
11 Generalized Drawing Primitive (GDP)
id Definition
1 Bar
2 Arc
3 Pie
4 Circle
5 Ellipse
6 Elliptical Arc
7 Elliptical Pie
8 Rounded rectangle
9 Filled rounded rectangle
10 Justified graphics text
12 Set character height absolute mode
14 Set color representation
15 Set polyline linetype
17 Set polyline color index
18 Set polymarker type
20 Set polymarker color index
21 Set text face
22 Set text color index
23 Set fill interior style
24 Set fill style index
25 Set fill color index
26 Inquire color representation
28 Input locator
31 Input string
32 Set writing mode
33 Set input mode
35 Inquire current polyline attributes
36 Inquire current polymarker
attributes
37 Inquire current fill area attributes
38 Inquire current graphic text
attributes
39 Set graphic text alignment
100 Open virtual screen workstation
101 Close virtual screen workstation
102 Extended inquire function
2-10
GEM VDI Programmer's Guide
Writing the Program
104 Set fill perimeter visibility
106 Set graphic text special effects
107 Set character cell height, points
mode
108 Set polyline and styles
109 Copy raster, opaque
110 Transform form
111 Set mouse form
112 Set user-defined fill pattern
113 Set user-defined linestyle
114 Fill rectangle
115 Inquire input mode
116 Inquire text extent
117 Inquire character cell width
118 Exchange timer interrupt vector
121 Copy raster, transparent
122 Show cursor
123 Hide cursor
124 Sample mouse button state
125 Exchange button change vector
126 Exchange mouse movement vector
127 Exchange cursor change vector
128 Sample keyboard state information
129 Set clipping rectangle
130 Inquire face name and index
131 Inquire current face information
Required Functions Printers require the following functions and
for Printers subfunctions:
Opcode Definition
1 Open workstation
2 Close workstation
3 Clear workstation
4 Update workstation
5 Escape
id Definition
1 Inquire addressable character
cells
20 Form advance
21 Output window
22 Clear display list
23 Output bit image file
2-11
GEM VDI Programmer’s Guide
Writing the Program
6
7
8
9
11
12
15
17
18
20
21
22
23
24
25
26
32
35
36
37
38
39
102
104
106
107
108
112
116
117
129
130
131
Polyline
Polymarker
Text
Filled area
Generalized Drawing Primitive (GDP)
id Definition
1 Bar
2 Arc
3 Pie
4 Circle
5 Ellipse
6 Elliptical Arc
7 Elliptical Pie
8 Rounded rectangle
9 Filled rounded rectangle
10 Justified graphics text
Set character height absolute mode
Set polyline linetype
Set polyline color index
Set polymarker type
Set polymarker color index
Set text face
Set text color index
Set fill interior style
Set fill style index
Set fill color index
Inquire color representation
Set writing mode
Inquire current polyline attributes
Inquire current polymarker
attributes
Inquire current fill area attributes
Inquire current graphic text
attributes
Set graphic text alignment
Extended inquire function
Set fill perimeter visibility
Set graphic text special effects
Set character height points mode
Set polyline end styles
Exchange fill pattern
Inquire text extent
Inquire character cell width
Set clipping
Inquire face name and index
Inquire current face information
2-12
GEM VDI Programmer's Guide
Writing the Program
Required Functions Plotters require the following functions and
for Plotters subfunctions:
Opcode Definition
1 Open workstation
2 Close workstation
3 Clear workstation
4 Update workstation
5 Escape
id Definition
1 Inquire addressable character
cells
6 Polyline
7 Polymarker
8 Text
9 Filled area
11 Generalized Drawing Primitive (GDP)
id Definition
1 Bar
2 Arc
3 Pie
4 Circle
5 Ellipse
6 Elliptical arc
7 Elliptical pie
8 Rounded rectangle
9 Filled rounded rectangle
10 Justified graphics text
12 Set character height absolute mode
15 Set polyline linetype
17 Set polyline color index
18 Set polymarker type
20 Set polymarker color index
21 Set text face
22 Set text color index
23 Set fill interior style
24 Set fill style index
25 Set fill color index
35 Inquire current polyline attributes
36 Inquire current polymarker
attributes
37 Inquire current fill area attributes
38 Inquire current graphic text
attributes
2-13
GEM VDI Programmer's Guide
Writing the Program
39 Set graphic text alignment
102 Extended inquire function
104 Set fill perimeter visibility
107 Set character height points mode
108 Set polyline end styles
116 Inquire text extent
117 Inquire character cell width
124 Set clipping
130 Inquire face name and index
131 Inquire current face information
Required Functions Because metafiles are transportable to any
for Metafiles device, the required functions are all those
common to any device you may use. Metafiles
support some inquiries by returning the opcode
number. Refer to Appendix C for the metafile
format of those supported inquires.
Metafiles require the following functions and
subfunctions:
Opcode Definition
1 Open workstation
2 Close workstation
3 Clear workstation
4 Update workstation
5 Escape
id Definition
1 Inquire addressable character
cells
2 Exit alpha mode
3 Enter alpha mode
20 Form advance
21 Output window
22 Clear display list
23 Output bit image file
98 Update metafile extents
99 Write metafile item
100 Change GEM VDI filename
6 Polyline
7 Polymarker
8 Text
9 Filled area
11 Generalized Drawing Primitive (GDP)
2-14
GEM VDI Programmer's Guide
Writing the Program
id Definition
1 Bar
2 Arc
3 Pie
4 Circle
5 Ellipse
6 Elliptical arc
7 Elliptical pie
8 Rounded rectangle
9 Filled rounded rectangle
10 Justified graphics text
12 Set character height absolute mode
13 Set character baseline vector
14 Set color representation
15 Set polyline linetype
16 Set polyline line width
17 Set polyline color index
18 Set polymarker type
19 Set polymarker height
20 Set polymarker color index
21 Set text face
22 Set text color index
23 Set fill interior style
24 Set fill style index
25 Set fill color index
26 Inquire color representation
32 Set writing mode
35 Inquire current polyline attributes
36 Inquire current polymarker
attributes
37 Inquire current fill area attributes
38 Inquire current graphic text
attributes
39 Set graphic text alignment
102 Extended inquire function
103 Contour fill
104 Set fill perimeter visibility
106 Set graphic text special effects
107 Set character height points mode
108 Set polyline end styles
112 Set fill pattern
113 Set user-defined line style pattern
114 Fill rectangle
117 Inquire character cell width
129 Set clipping rectangle
131 Inquire current face information
2-15
GEM VDI Programmer's Guide
Writing the Program
Available
Opcodes
You can determine if a function is available
in a specific driver in one of the following
ways:
• Check the information about available
features returned from the Open Workstation
function or the Extended Inquire function.
• Check the selected value returned from an
opcode against the requested value. If the
two values are not the same, then either the
function is not available or the requested
value is not available, and GEM VDI selected
a best fit value.
Format
The following is the format for the parameters
for all GEM VDI functions.
Input Parameters contrl(O) — Opcode number for the GEM VDI
function.
contrl(l) — Number of vertices in the
ptsin array.
Each vertex consists of an
x,y coordinate pair, so the
length of the ptsin array is
twice the number of specified
vertices
contrl(3) — Length of integer array intin.
contrl(5) — Subfunction identification
number for a Generalized
Drawing Primitive (GDP) or
Escape.
contrl(6) — Device handle.
contrl(7-n) — Opcode-dependent information.
intin — Array of integer input
parameters.
2-16
GEM VDI Programmer's Guide
Writing the Program
ptsin — Array of input point
coordinate data.
Refer to the Extended Inquire
function in Section 8 for
information on how to
determine the maximum size
for the ptsin array.
Output Parameters contrl(2) — Number of vertices in the
ptsout array.
Each vertex consists of an
x,y coordinate pair, so the
length of the ptsout array is
twice the number of specified
vertices.
contrl(4) — Length of integer array
intout.
contrl(6) — Device handle.
contrl(7-n) — Opcode-dependent information.
intout — Array of integer output point
parameters.
ptsout — Array of output point
coordinate data.
CALLING Because both input and output coordinates
CONVENTIONS may be converted by the GDOS, the calling
routine must ensure that the vertex count,
contrl(l), is set correctly. Contrl(l) must be
set to 0 if no x,y coordinates are being passed
to GEM VDI by the application program. In
addition, the input integer count, contrl(3),
must always be set. The calling routine must
set contrl(3) to 0 if no integers are being
passed to GEM VDI. Similarly, contrl(2), the
output vertex count, and contrl(4), the output
integer count, are always set correctly by GEM
VDI. These values contain zeros if no
information is being passed back in ptsout and
intout, respectively.
The double-word addresses of the five parameter
arrays are stored in a ten-word data structure
referred to as a Parameter Block (PB) .
2-17
GEM VDI Programmer's Guide
Calling Conventions
Registers and
Interrupts
RUNNING GRAPHICS
APPLICATIONS
UNDER GEM VDI
Refer to Appendix E for the specific
registers and interrupts for various operating
systems.
Table 2-1. Parameter Block Contents
Address
Contents
PB
control array (contrl)
PB + 4
input parameter array (intin)
PB + 8
input point coordinate
array (ptsin)
PB + 12
output parameter array (intout)
PB + 16
output point coordinate
array (ptsout)
To use the graphics features provided by
GEM VDI, you must ensure that the following
conditions are met:
1. Your application program must conform to the
GEM VDI calling convention to access
graphics primitives. This process involves
the application making a call to the GDOS
and using the interrupt for your operating
system. Refer to Appendix E for the
specific interrupts.
The parameter list provides information to
GEM VDI and returns information to the
calling program. The details of parameter
passing are in the previous section.
2. Enough stack space must be available for GEM
VDI operations. This space includes a
buffer area for transforming points passed
to GEM VDI and some fixed overhead space.
The formula to determine the required stack
space is discussed under "Determining Memory
Requirements" later in this section.
2-18
GEM VDI Programmer's Guide
Running Graphics Applications
3. When your program is executed, the required
device drivers must be present on the disk
specified in the GEM VDI graphics-mode
command, or in the current default drive if
no drive is specified. The ASSIGN.SYS file
must contain the names of your device
drivers and a device ID number for each
device driver. Refer to "ASSIGN.SYS" in
Section 1 for information about creating an
ASSIGN.SYS file.
4. After successfully compiling or assembling
and linking your application program, you
can run it like any program, once GEM VDI is
active. You can enable GEM VDI graphics
with the GEMVDI graphics-mode command,
described under "Enabling Graphics" below.
ENABLING GRAPHICS Special commands let you enable graphics
functions from the command level of the
operating system.
To load GEM VDI and start a non-GEM application
that uses the VDI (like a test program or
debugger), type the following command:
GEMVDI /FILENAME
To load GEM VDI and start a GEM application,
type the following command:
GEMVDI FILENAME
To load GEM VDI and start the GEM Desktop™
application, type the following command:
GEMVDI
Each command loads GDOS and any drivers
declared resident in the ASSIGN.SYS file.
ASSIGN.SYS and the driver files must be located
in one of the directories in the current search
path.
Any application to be invoked by a GEMVDI
command must also be located in the search
path.
2-19
GEM VDI Programmer's Guide
Disabling Graphics
DISABLING GRAPHICS When the application invoked by the GEMVDI
command terminates, GEM VDI relinquishes all
system memory space, leaving the maximum memory
for nongraphics programs.
DETERMINING MEMORY To determine the amount of stack space
REQUIREMENTS required to run a given application, make the
following calculation:
Open workstation call = approximately 128
bytes
All other calls = ptsin size + 128 bytes +
the overhead requirements
of the operating system
Ptsin is the point array passed to the device
driver from the application program (two words
for each point).
The stack requirement is the larger of the two
resulting values. This stack space must be
available in the application program stack
area.
GEM VDI requires less than 30 kilobytes in
memory for a single open driver. This space is
allocated when you enter the GEM VDI graphics¬
mode command.
DEBUGGING GRAPHICS Graphics programs can be debugged with a
APPLICATIONS debugging tool. The default device drivers
UNDER GEM VDI and GDOS are loaded after you enter the GEMVDI
command. Your graphics application program is
loaded in the normal manner for programs on
your operating system.
End of Section 2
2-20
Section 3
Control Functions
INTRODUCTION
The control functions initialize the graphics
workstation and set defaults for use with the
application.
OPEN WORKSTATION
The Open Workstation function loads a graphics
device driver for the application program and
returns a device handle. The device is
initialized with the parameters in the input
array. Information about the device is
returned; additional dev i ce-specif ic
information is returned in the Extended Inquire
function.
If the device is a screen, it is initialized to
graphics mode. GEM VDI clears the display
surface.
If the device cannot be opened, GEM VDI returns
a zero as the device handle in contrl(6). Any
nonzero value in contrl(6) indicates a
successful operation.
Input contrl(O) —
contrl(l) —
contrl(3) —
intin
intin(O) —
intin(l)
intin(2)
intin(3)
intin(4) —
intin(5) —
intin(6)
intin(7)
intin(8) —
intin(9)
Opcode = 1.
Number of input vertices = 0.
Length of intin array = 11.
Initial defaults (for example,
linestyle, color, character
size).
Device id number.
This value determines which
device driver to dynamically
load in memory.
Linetype.
Polyline color index.
Marker type.
Polymarker color index.
Text face.
Text color index.
Fill interior style.
Fill style index.
Fill color index.
3-1
GEM VDI Programmer's Guide
Open Workstation
intin(10) — NDC to RC transformation flag.
0 = Map the full NDC space to
the full RC space.
1 = Reserved.
2 = Use the RC system.
Output
contrl(2)
contrl(4)
contrl(6)
intout(0)
intout(1)
intout (2)
Number of output vertices = 6.
Length of intout array = 45.
Device handle for this device.
Maximum addressable width of
screen or plotter in rasters or
steps, assuming a 0 start point
(for example, a resolution of
640 implies an addressable area
of 0-639, so intout(0)=639).
Maximum addressable height of
screen or plotter in rasters or
steps, assuming a 0 start point
(for example, a resolution of
480 implies an addressable area
of 0-479, so intout(1)=479).
Device Coordinate units flag.
0= Device capable of
producing precisely scaled
image (typically a plotter
or a printer).
1 = Device not capable of
producing precisely scaled
image (typically a film
recorder).
intout (3)
intout(4)
intout(5)
— Width
step,
screen)
— Height
step,
screen)
Number
of one pixel (plotter
or aspect ratio for
in microns.
of one pixel (plotter
or aspect ratio for
in microns,
of character heights.
0 = Continuous scaling.
intout(6)
intout(7)
Number
Number
of linetypes.
of line widths.
0 = Continuous scaling.
intout(8)
Number
of marker types.
3-2
GEM VDI Programmer's Guide
Open Workstation
intout(9) — Number of marker sizes.
0 = Continuous scaling.
intout(lO) — Number of faces supported
by device (not the highest
numbered face index).
intout(ll) — Number of patterns.
intout(12) — Number of hatch styles,
intout(13) — Number of predefined colors (2
for monochrome devices).
This is the number of colors
that can be displayed on the
device simultaneously.
intout(14) — Number of Generalized Drawing
Primitives (GDPs).
intout(15) to
intout(24) — Linear list of the first ten
supported GDPs.
The number indicates which GDP
is supported. A -1 indicates
the end of the list of
supported GDPs. GEM VDI
defines ten GDPs.
1 — Bar
2 — Arc
3 — Pie slice
4 — Circle
5 — Ellipse
6 — Elliptical arc
7 — Elliptical pie
8 — Rounded rectangle
9 — Filled rounded rectangle
10 — Justified graphics text
intout(25) to
intout(34) — Linear list of attribute set
associated with each GDP.
0 — Polyline
1 — Polymarker
2 — Text
3 — Fill area
4 — None
intout(35) — Color capability flag.
0 — No
1 — Yes
3-3
GEM VDI Programmer's Guide
Open Workstation
intout(36) —
intout(37) —
intout(38) —
intout(39) —
intout(40) —
intout(41) —
intout(42) —
intout(43) —
Text rotation capability flag.
0 — No
1 — Yes
Fill area capability flag.
0 — No
1 — Yes
Cell array operation capability
flag.
0 — No
1 — Yes
Number of available colors
(total number of colors in
color palette).
0 — Continuous device
(more than 32767 colors)
2 — Monochrome (black and
white)
>2 — Number of colors
available
Number of locator devices
available.
1 — Keyboard only
2 — Devices with keyboard and
other input
Number of valuator devices
available.
1 — Keyboard
2 — If another valuator device
is available
Number of choice devices
available.
1 — Function keys on keyboard
2 — If another button pad is
available
Number of string devices
available.
1 — Keyboard
3-4
GEM VDI Programmer's Guide
Open Workstation
intout(44) —
ptsout(O)
ptsout(l) —
ptsout(2)
ptsout(3)
ptsout(4)
ptsout(5) —
ptsout(6) —
ptsout(7)
ptsout(8)
ptsout(9)
ptsout(lO) —
ptsout(ll) —
Workstation type.
0 — Output only
1 — Input only
2 — Input/output
3 — Reserved
4 — Metafile output
Minimum character width.
Minimum character height in the
y-axis in the current
coordinate system.
The minimum and maximum
character heights are the
actual character body (baseline
to top line), not the character
extent box, which may include
extra space used for interline
or intercharacter spacing.
Maximum character width.
Maximum character height in the
y-axis in the current
coordinate system.
Minimum line width in the x-axis
in current coordinate system.
The minimum line width is a
nominal device-dependent size.
If the minimum line width used
is 1 device unit, the line may
not be visible on some high-
resolution devices.
0 .
Maximum line width in the x-axis
in the current coordinate
system.
0 .
Minimum marker width in x-axis
in the current coordinate
system.
Minimum marker height in x-axis
in the current coordinate
system.
Maximum marker width in x-axis
in the current coordinate
system.
Maximum marker height in x-axis
in the current coordinate
system.
3-5
GEM VDI Programmer's Guide
Open Workstation
Default Color The default color table is set up differently
Tables for monochrome and color devices.
Table 3-1. Monochrome Screens
Index
Color
0
White
1
Black
Table 3-2. Monochrome Printer/Plotters
Index
Color
0
White
1
Black
Table 3-3. Color Screens
Index
Color
0
White
1
Black
2
Red
3
Green
4
Blue
5
Cyan
6
Yellow
7
Magenta
8
White
9
Black
10
Light Red
11
Light Green
12
Light Blue
13
Light Cyan
14
Light Yellow
15
Light Magenta
16-n
Device-dependent
3-6
GEM VDI Programmer's Guide
Open Workstation
Other default values set by the driver during
initialization are listed in Table 3-4.
Table 3-4. Default Values
Attribute
Default Value
Character height
Nominal character
height
Character baseline
rotation
0 degrees rotation
Text alignment
Left baseline
Text style
Normal intensity
Line width
Nominal line width
Marker height
Nominal marker height
Polyline end styles
Squared
Writing mode
Replace
Input mode
Request for all input
classes (locator,
valuator, choice,
string)
Fill area perimeter
visibility
Visible
User-defined line
style
Solid
User-defined fill
pattern
Solid
Cursor
Hidden
Clipping
Disabled
3 -'
GEM VDI Programmer's Guide
Open Workstation
C BINDING
Procedure Name v_opnwk( work_in, Schandle, work_out )
Data Types WORD v_opnwk ( );
WORD work_in[ll];
WORD handle;
WORD wo rk_ou t[5 7];
Input Arguments work__in[0] = intin[0]
work_in[l] = intin[l]
work_in[10] = intin[10]
Output Arguments handle = contrl[6]
work_out[0] = intoutCO]
work_out[l] = intout[l]
work_out[44] = intout[44]
work_out[45] = ptsoutCO]
work_out[56] = ptsout[ll]
3-8
GEM VDI Programmer's Guide
Close Workstation
CLOSE WORKSTATION
The Close Workstation function terminates the
graphics device properly (returning you to
alpha mode) and prevents any further output to
the device. If the device is a screen, the
alpha device is selected, and the graphics
device is deselected. If the device is a
printer, an update occurs if one has not just
taken place. For a metafile, GEM VDI flushes
the buffer and closes the metafile.
Note: Close
before closing
your open virtual workstations
the workstation.
Input
contrl(O) —
contrl(l) —
contr1(3) —
contrl(6) —
Opcode = 2.
Number of input vertices = 0.
Length of intin array = 0.
Device handle.
Output
contrl(2) —
contrl(4) —
Length of output vertices = 0.
Length of intout array = 0.
C BINDING
Procedure Name
v_clswk( handle )
Data Types
WORD v_clswk (
WORD handle;
) 7
Input Arguments
handle = contrl[6]
3-9
GEM VDI Programmer's Guide
Open Virtual Screen Workstation
OPEN VIRTUAL
SCREEN WORKSTATION
Input
This function allows a single physical screen
to act as multiple workstations. Each
workstation has access to the entire screen.
However, attribute environments for each
workstation are maintained separately. For
example, the workstation may have different
transformation modes, clipping rectangles, and
so on.
Note: Not all input devices associated with
the virtual workstation will work.
The input to the Open Virtual Screen
Workstation function is the device handle of a
currently open physical screen workstation and
an environment initialization array (see "Open
Workstation"). If the virtual screen
workstation can be opened, a new device handle
is returned for the virtual workstation. The
device capabilities arrays for the physical
screen workstations are returned as they are
for the Open Workstation function. If the
virtual screen workstation cannot be opened, a
zero is returned as the device handle to
indicate an unsuccessful request.
contrl(0)
contrl(l)
contrl(3)
contrl(6)
Opcode = 100.
Number of input vertices = 0.
Length of intin = 11.
Device handle of a previously
opened screen device.
intin — For a description of the intin
parameters required in the
intin array see Open
Workstation (Opcode 1).
3-10
GEM VDI Programmer's Guide
Open Virtual Screen Workstation
Output contr1(2) —
contrl(4) —
contrl(6) —
Warning:
Wote:
Number of output vertices = 6.
Length of intout = 45.
The device handle for the
Virtual Screen Device just
opened.
Contrl(6) is an input/output
parameter. The value is
changed to that of the Virtual
Screen Workstation device
handle.
All output parameters are the
same as those of Open
Workstation (Opcode 1).
3-11
GEM VDI Programmer's Guide
Open Virtual Screen Workstation
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
v_opnvwk{ work_in, &handle, work_out )
WORD v_opnvwk( );
WORD handle?
WORD work_in[11]?
WORD work out[57]?
handle = contrl[6]
work_in[0] = intin[0]
work__in[10] = intin[10]
work_out[0] = intoutCO]
work__out[44] = intout[44]
work_out[45] = ptsout[0]
work_out[563 = ptsout[ll]
3-12
GEM VDI Programmer's Guide
Close Virtual Screen Workstation
CLOSE VIRTUAL
SCREEN WORKSTATION
The Close Virtual Screen Workstation function
terminates the virtual device and prevents any
further output to it.
Input
contrl(0)
contrl(l)
contrl(3)
contrl(6)
—
Opcode
Number
Length
Device
= 101.
of input vertices = 0.
of intin = 0.
handle.
Output
contrl(2)
contrl(4)
—
Number
Length
of output vertices = 0.
of intout = 0.
C BINDING
Procedure Name
v_clsvwk(
handle )
Data Types
WORD v clsvwk(
WORD handle;
);
Input Arguments handle = contrl[6]
3-13
GEM VDI Programmer's Guide
Clear Workstation
CLEAR WORKSTATION The Clear Workstation function erases the
screen. GEM VDI sets the screen to the
currently selected background color, which is
defined as color index zero. If the device is
a plotter without paper advance, GEM VDI
prompts the operator to load a new page. If
the device is a printer, data in the buffer is
erased and a new page occurs. For a metafile,
GEM VDI outputs the opcode. No output occurs
for any device.
Note: With GEM VDI, you do not need to do a
Clear Workstation after an Open Workstation
because the display is cleared at Open
Workstation.
Input contrl(O) — Opcode = 3.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin = 0.
contrl(6) — Device handle.
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout = 0.
C BINDING
Procedure Name v_clrwk( handle )
Data Types WORD v_clrwk ( );
WORD handle;
Input Arguments handle = contrl[6]
3-14
GEM VDI Programmer's Guide
Update Workstation
UPDATE WORKSTATION The Update Workstation function causes all
pending graphics commands to be executed
immediately, in the order the commands were
stored in the buffer. For printer drivers, you
must use this function to start output to the
printer. This function has no effect on
screens. Plotters execute all the commands in
the buffer. When the plotter buffer is empty,
it returns from the Update Workstation
function. For a metafile, GEM VDI outputs the
opcode.
Note: The picture is drawn to the printer but
no new page occurs. A Clear Workstation causes
a new page.
Input
contrl(0)
contrl(l)
contrl(3)
contrl(6)
Opcode = 4.
Number of input vertices = 0.
Length of intin = 0.
Device handle.
Output contrl(2) — Number in output vertices = 0.
contrl(4) — Length of intout = 0.
C BINDING
Procedure Name
v_updwk( handle )
Data Types
WORD v_updwk ( );
WORD handle;
Input Arguments
handle = contrl[6]
3-15
GEM VDI Programmer's Guide
Load Fonts
LOAD FONTS This function loads the fonts associated with a
particular driver in the ASSIGN.SYS file. It
then makes them available to the appropriate
program.
GEM VDI returns the number of newly generated
font identifiers. If the fonts were already
available to the workstation, no action occurs,
and GEM VDI returns a zero for the number of
additional font identifiers.
Note: You do not need to invoke this function
if the default system fonts for a particular
driver are sufficient.
Input contrl(O) — Opcode = 119.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 1.
contrl(6) — Device handle.
intin(O) — Reserved for future use = 0.
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of output array = 1.
intout(O) — Number of additional font
identifiers.
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
additional = vst_load_fonts( handle, select )
WORD vst_load_fonts( );
WORD additional;
WORD handle;
WORD select;
handle = contrl[6]
select = intin[0]
additional = intout[0]
3-16
GEM VDI Programmer's Guide
Unload Fonts
UNLOAD FONTS This function logically dissociates the external
fonts loaded by the Load Fonts function from a
device and unloads them from memory, if
possible. A device handle is passed into the
function identifying the device whose external
fonts are to be unloaded.
If the fonts are being shared by other virtual
workstations with the same root device handle,
the fonts are not unloaded from memory until
one of the following conditions is met:
• all workstations that share the fonts are
closed
•all workstations that share the external
fonts request that the external fonts be
unloaded
The default system fonts for the workstation
remain loaded and available.
Input
contrl(0)
contrl(l)
contrl(3)
contrl(6)
Opcode = 120.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(0)
Reserved for future use.
Output
contrl(2)
contrl(4)
Number of
Length of
output vertices =
intout array = 0.
0 .
3-17
GEM VDI Programmer's Guide
Unload Fonts
C BINDING
Procedure Name
Data Types
Input Arguments
vst_unload fonts( handle.
WORD vst_unload_fonts( );
WORD handle;
WORD select;
handle = contrl[6]
select = intin[0]
select )
3-18
GEM VDI Programmer's Guide
Set Clipping Rectangle
SET CLIPPING
RECTANGLE
Input
This function enables or disables clipping of
all output primitives by GEM VDI. Intin (0) is a
flag, which if nonzero, enables clipping. The
ptsin array contains the rectangle, specified
in the current coordinate system, to clip to.
If intin(O) is zero, clipping is turned off.
The default at Open Workstation is for clipping
to be disabled.
contrl(0)
contrl(1)
contrl(3)
contrl(6)
Opcode = 129.
Number of input vertices = 2.
Length of intin array = 1.
Device handle.
intin(0)
ptsin(0)
ptsin (1)
ptsin(2)
ptsin(3)
Clipping flag.
0 = Turn clipping off.
non-zero = Turn clipping on.
x-coordinate of corner of the
clipping rectangle in NDC/RC
units.
y-coordinate of corner of the
clipping rectangle in NDC/RC
units.
x-coordinate of corner diagonally
across from the corner selected
in ptsin(0) of the clipping
rectangle in NDC/RC units,
y-coordinate of corner diagonally
across from the corner selected
in ptsin(l) of the clipping
rectangle in NDC/RC units.
3-19
GEM VDI Programmer's Guide
Set Clipping Rectangle
C BINDING
Procedure Name
Data Types
Input Arguments
vs_clip( handle, clip_flag, pxyarray )
WORD vs_clip();
WORD handle?
WORD clip_flag;
WORD pxyarray[4]?
handle = contrl[6]
clip_flag = intin[0]
pxyarray[0] = ptsin[0]
pxyarray[l] = ptsin[l]
pxyarray[2] = ptsin[2]
pxyarray[3] = ptsin[3]
End of Section 3
Section 4
Output Functions
INTRODUCTION
POLYLINE
The output functions display graphics primitives
(polyline or circle, for example) on devices.
This function displays a polyline on the
graphics device. The starting point for the
polyline is the first point in the input array.
Lines are drawn between subsequent points in
the array. GEM VDI displays a zero length line
(degenerate case) as a point. GEM VDI will not
display a single coordinate pair. Lines are
drawn using the following current line
attributes:
• color
• linetype
• line width
• end style
• current writing mode
For wide lines, the first point (ptsin(O),
ptsin(l)) is drawn as shown in Figure 4-1.
Figure 4-1. First Point for Wide Lines
4-1
laMa vui t-rogrammer ■ s Guide
Polyline
Input contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
ptsin
ptsin(O)
ptsin(l)
ptsin(2)
ptsin(3)
Opcode = 6.
Number of vertices (x,y pairs)
in polyline = n.
(Maximum number is returned in
Extended Inquire.)
Length of intin array = 0.
Device handle.
Array of coordinates of polyline
in NDC/RC units.
x-coordinate of first point in
NDC/RC units.
y-coordinate of first point in
NDC/RC units.
x-coordinate of second point in
NDC/RC units.
y-coordinate of second point in
NDC/RC units.
x-coordinate of last point in
NDC/RC units.
y-coordinate of last point in
NDC/RC units.
ptsin(2n-2) —
ptsin(2n-l) —
Output
contrl(2)
contrl(4)
Number of output
Length of intout
vertices =
array = 0.
0 .
4-2
GEM VDI Programmer's Guide
Polyline
C BINDING
Procedure Name
Data Types
Input Arguments
v_pline( handle, count, pxyarray )
WORD v_pline ( );
WORD handle;
WORD count;
WORD pxyarray[2 * count];
handle = contrl[6]
count = contrl[l]
pxyarray[0] = ptsin[0]
pxyarrayfl] = ptsin[l]
pxyarray[2n-2] = ptsin[2n-2]
pxyarray[2n-l] = ptsin[2n-l]
4-3
GEM VDI Programmer'
's Guide
Polymarker
POLYMARKER
This function draws markers at the points
specified in the input array. GEM VDI displays
the markers using the current marker
attributes:
• color
• scale
• type
• writing mode
Input
contrl(O) —
contrl(l) —
Opcode = 7 .
Number of markers = n.
(Maximum number is returned in
Extended Inquire.)
contrl(3) —
contrl(6) —
Length of intin array = 0.
Device handle.
ptsin
Array of coordinates in NDC/RC
units.
ptsin(O)
ptsin(l)
ptsin(2)
ptsin{3)
x-coordinate of first marker in
NDC/RC units.
y-coordinate of first marker in
NDC/RC units.
x-coordinate of second marker in
NDC/RC units.
y-coordinate of second marker in
NDC/RC units.
ptsin(2n-2) --
ptsin(2n-l) —
x-coordinate of last marker in
NDC/RC units.
y-coordinate of last marker in
NDC/RC units.
Output
contrl{2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 0.
4-4
GEM VDI Programmer's Guide
Polymarker
C BINDING
Procedure Name
Data Types
Input Arguments
v_pmarker( handle, count, pxyarray )
WORD v_pmarker ( );
WORD handle;
WORD count;
WORD pxyarray[2 * count];
handle = contrl[6]
count = contrl[l]
pxyarray[Oj = ptsin[0]
pxyarray[l] = ptsin[lj
pxyarray[2n-2] = ptsin[2n-2]
pxyarray[2n-l] = ptsin[2n-l]
4-5
GEM VDI Programmer's Guide
Text
TEXT
This function writes graphic text to the display
surface. The (x,y) position specified by the
application program is the alignment point of
the text string. The Set Graphic Text
Alignment function establishes the relationship
between the starting point of the string and
the specified x,y position. The default
alignment is the left baseline position of the
text string. Refer to the Set Graphic Text
Alignment function in Section 5 for an
illustration of alignment points.
Each word of the intin array contains one
character in bits 0-7. Any unsupported
character is mapped to a symbol for an
undefined character.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 8.
Number of input vertices = 1.
Length of intin array = n.
Device handle.
intin
Character string as ASCII codes
in 16-bit words.
The maximum number of
characters equals the size of
the intin array. See Extended
Inquire.
ptsin(O)
ptsin(l)
x-coordinate of alignment point
of text in NDC/RC units,
y-coordinate of alignment point
of text in NDC/RC units.
Output
contrl{2) —
contrl{4) —
Number of output vertices = 0.
Length of intout array = 0.
GEM VDI Programmer's Guide
Text
C BINDING
Procedure Name
Data Types
Input Arguments
v_gtext( handle, x, y, string )
WORD v_gtext ( );
WORD handle;
WORD x;
WORD y?
BYTE string[n];
handle = contrl[6]
x = ptsin[0]
y = ptsin[l]
string = intin
Note: Bytes for the string array are mapped
into the eight least significant bits of intin.
The string must be null-terminated.
4-7
GEM VDI Programmer's Guide
Filled Area
FILLED AREA This function fills a complex (for example,
self-intersecting) polygon specified by the
input array. The area is filled using the
following current attributes:
• fill area color
• interior style (hollow, solid, pattern, hatch
or user-defined)
• writing mode
• style index
The area is outlined with a solid line of the
current fill area color if the fill area
perimeter visibility is on, which is the
default at Open Workstation. See the Set Fill
Perimeter Visibility function in Section 5.
If a device does not have area fill capability,
GEM VDI outlines the polygon using the current
fill area color. The device driver ensures
that the fill area is closed by connecting the
first point to the last point.
GEM VDI displays a polygon with zero area as a
dot. If outline isn't turned on, the
degenerate case isn't displayed as a dot. GEM
VDI does not display a polygon with only one
endpoint. The maximum number of filled area
vertices may be determined with the Extended
Inquire function.
4-8
GEM VDI Programmer's Guide
Filled Area
Input contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
ptsin
ptsin(O) —
ptsin(l) —
ptsin(2) —
ptsin(3) —
ptsin(2n-2) —
ptsin(2n-l) —
Opcode = 9.
Number of vertices in polygon =
n.
Maximum number returned in
Extended Inquire.
Length of intin array = 0.
Device handle.
Array of coordinates of polygon
in NDC/RC units,
x-coordinate of first point in
NDC/RC units.
y-coordinate of first point in
NDC/RC units.
x-coordinate of second point in
NDC/RC units.
y-coordinate of second point in
NDC/RC units.
x-coordinate of last point in
NDC/RC units.
y-coordinate of last point in
NDC/RC units.
Output
contr1(2)
contrl (4)
Number of output vertices = 0.
Length of intout array = 0.
4-9
GEM VDI Programmer's Guide
Filled Area
C BINDING
Procedure Name
Data Types
Input Arguments
v_fillarea( handle, count,
WORD v_fillarea ( );
WORD handle;
WORD count;
WORD pxyarray[2 * count];
handle = contrl[6]
count = contrl[l]
pxyarray[0] = ptsin[0]
pxyarrayfl] = ptsin[l]
pxyarray[2n-2] = ptsin[2n-
pxyarray[2n-l] = ptsin[2n-
pxyarray )
2 ]
1 ]
4-10
GEM VDI Programmer's Guide
Cell Array
CELL ARRAY
Input
With the Cell Array function, the device draws a
rectangular array defined by the input
parameter (x,y) coordinates and the color index
array. The lower left and upper right
coordinates define the extent of the rectangle.
GEM VDI divides the rectangle into cells based
on the number of rows and columns specified as
input parameters. The color index array
specifies the color for each cell.
Each cell of the rectangle is mapped to pixels
on the display surface. The pixel takes the
color of the cell that covers its center.
If the device does not support cell arrays, the
device outlines the area with a solid line in
the current line color and line width.
Note: This function is not required and may
not be available on all devices.
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
contrl(7) —
contrl{8) —
contrl(9) —
contrl (10) —
Opcode = 10.
Number of input vertices = 2.
Length of color index array.
Device handle.
Length of each row in color
index array (size as declared
in a high-level language).
Number of elements used in each
row of color index array.
Number of rows in color index
array.
Pixel operation to be performed.
(See Set Writing Mode function
in Section 5 for
description of each mode.
the
)
intin(O)
Color index array, stored by
row.
ptsin(O) —
x-coordinate of lower
corner in NDC/RC units.
left
ptsin(l)
y-coordinate of lower
corner in NDC/RC units.
left
ptsin(2) —
x-coordinate of upper
corner in NDC/RC units.
right
ptsin(3)
y-coordinate of upper
corner in NDC/RC units.
right
4-11
GEM VDI Programmer's Guide
Cell Array
Output
C BINDING
Procedure Name
Data Types
Input Arguments
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intin array = 0.
v_cellarray( handle, pxyarray, row_length,
el_used, num_rows, wrtjmode, colarray )
WORD v_cellarray( );
WORD handle;
WORD pxyarray[4];
WORD row_length;
WORD el_used;
WORD num_rows;
WORD wrt_mode;
WORD colarray[num_rows*el_used];
handle = contrl[6]
pxyarray[0] = ptsine[0]
pxyarraytl] = ptsin[l]
pxyarray[2] = ptsin[2]
pxyarray[3] = ptsin[3]
row_length = contrl[7]
el_used = contrl[8]
num_rows = contrl[9]
wrt_mode = contrl[10]
colarray[0] = intin[0]
colarray[n] = intin[n]
4-12
GEM VDI Programmer's Guide
Contour Fill
CONTOUR FILL This function fills an area until it finds
either the edges of the display surface or the
color index stated in intin(0). This function
is sometimes called a seed fill or a flood
fill. If intin(0) is negative, the algorithm
searches for any color other than the color of
the seed point. GEM VDI fills the area using
the current fill area attributes.
Note: This function is not required and may
not be available on all devices.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl (6) —
Opcode = 103.
Number of input vertices = 1.
Length of intin array = 1.
Device handle.
intin(O)
Color index that defines the
contour.
ptsin(O)
ptsin(l) —
x-coordinate of starting point
in NDC/RC units,
y-coordinate of starting point
in NDC/RC units.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name v_contourfill( handle, x, y, index )
Data Types WORD v_contourfill ( );
WORD handle;
WORD x;
WORD y;
WORD index;
Input Arguments handle = contrl[6]
x = ptsin[0]
y = ptsinfl]
index = intin[0]
4-13
GEM VDI Programmer's Guide
Fill Rectangle
FILL RECTANGLE This function fills a rectangular area with the
pattern defined by the current fill area
attributes. The rectangle is filled using all
fill area attributes except outline.
Input contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
ptsin(O)
ptsin(l)
ptsin(2)
ptsin(3)
Opcode = 114.
Number of input vertices = 2.
Length of intin array = 0.
Device handle.
x-coordinate
of corner
of
destination
r ec tangle
in
RC/NDC.
y-coordinate
of corner
of
destination
r ec tangle
i n
RC/NDC.
x-coordinate
of corner
of
destination rectangle in RC/NDC
diagonally opposite corner
specified in ptsin(O).
y-coordinate of corner of
destination rectangle in RC/NDC
diagonally opposite corner
specified in ptsin(l).
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name
vr_recfl( handle, pxyarray )
Data Types
WORD vr_recfl ( );
WORD handle;
WORD pxyarray[4];
Input Arguments handle = contrl[6]
pxyarray[0] = ptsin[0]
pxyarray[3] = ptsin[3]
4-14
GEM VDI Programmer's Guide
GDP
GENERALIZED
DRAWING PRIMITIVE
(GDP)
The contents of the control and data arrays are
different for each GDP.
For the arc, pie, elliptical arc, and
elliptical pie, the information in the radius,
start, and end angle variables defines the GDP.
All angle specifications are in tenths of
degrees and assume that 0 degrees is 90 degrees
to the right of vertical, with values
increasing in the counterclockwise direction.
Arcs are drawn counterclockwise. All radius
specifications except for ellipse and
elliptical arc, assume an extent (distance) in
the x-axis. Ellipse and elliptical arc use
both x and y radius values. Refer to Figure 4-
2 .
The Generalized Drawing Primitive (GDP)
function allows you to use the predefined
primitives. The application can draw special
elements, such as arcs, circles, and ellipses
using this function.
900
1800 -0
2700
Figure 4-2. Angle Specification
Input contrl(0) —
contrl(l) —
contrl(3) —
contrl(5) —
1 — BAR:
4 — CIRCLE:
Opcode = 11.
Number of vertices in ptsin.
Length of input array intin.
Primitive id.
Uses fill area attributes (fill
interior style, style index,
writing mode, color and
perimeter style).
Uses fill area attributes (fill
interior style, style index,
writing mode, fill color and
perimeter style).
4-15
GEM VDI Programmer's Guide
GDP
2 —
3 —
5 —
6 —
7 —
8 —
9 __
10 -
Uses line attributes (color,
linetype, writing mode, width,
and end styles).
Uses fill area attributes
(interior style, writing mode,
fill style, fill color, and
perimeter style).
Uses fill area attributes (fill
interior style, writing mode,
style index, color, and
perimeter style).
ELLIPTICAL
ARC: Uses line attributes (color,
linetype, writing mode, width,
and end styles).
ELLIPTICAL
PIE: Uses fill area attributes (fill
interior style, writing mode,
style index, color and
perimeter style).
ROUNDED
RECTANGLE:
Uses line attributes (color,
linetype, writing mode, and
width).
FILLED
ROUNDED
RECTANGLE:
Uses fill area attributes (fill
interior style, writing mode,
style index color, and
perimeter style, color, and
width).
JUSTIFIED
GRAPHICS
TEXT: Uses text attributes (face,
character height, character
baseline vector, color index,
special effects, and
alignment).
ARC:
PIE:
ELLIPSE:
contr1(6)
Device handle.
ptsin
Array of coordinates for GDPs in
NDC/RC units.
ptsin(0)
ptsin(1)
ptsin(2)
x-coordinate of first point in
NDC/RC units.
y-coordinate of first point in
NDC/RC units.
x-coordinate of second point in
NDC/RC units.
4-16
GEM VDI Programmer's Guide
GDP
ptsin(3)
ptsin(2n-2)
ptsin(2n-l)
intin
y-coordinate of second point in
NDC/RC units.
— x-coordinate of last point in
NDC/RC units.
— y-coordinate of last point in
NDC/RC units.
— Angle for arcs and pies or
characters for justified
graphics text.
4-17
GEM VDI Programmer's Guide
BAR
BAR
Opcode = 11.
Number of input vertices = 2.
Length of intin array = 0.
Primitive id = 1.
Device handle.
x-coordinate of corner of bar in
NDC/RC units.
y-coordinate of corner of bar in
NDC/RC units.
x-coordinate of corner
diagonally opposite the corner
selected in ptsin(O) of bar in
NDC/RC units.
y-coordinate of corner
diagonally opposite the corner
selected in ptsin(l) of bar in
NDC/RC units.
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name v_bar( handle, pxyarray )
Data Types WORD v_bar ( );
WORD handle;
WORD pxyarray[4];
Input Arguments handle = contrl[6]
pxyarray[0] = ptsin[0]
pxyarrayfl] = ptsin[l]
pxyarray[2] = ptsin[2]
pxyarray[3] = ptsin[3]
Input contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
ptsin{0)
ptsin(l)
ptsin(2)
ptsin(3)
4-18
GEM VDI Programmer's Guide
ARC & PIE
ARC & PIE These functions are not required and may not be
available on all devices. GEM VDI requires the
specification of the arc by the angle
(intin(O),intin(1)).
Input
contrl(0)
Opcode = 11.
contr1(1)
—
Number of input vertices = 4.
contrl(3)
—
Length of intin array = 2.
contrl(5)
—
Primitive id.
2 = ARC
3 = PIE
contrl(6)
—
Device handle.
intin(0)
—
Start angle (in tenths of
degrees 0-3600),
counterclockwise.
intin(1)
"
End angle (in tenths of degrees
0-3600) .
ptsin(0)
—
x-coordinate of center point of
arc in NDC/RC units.
ptsin(1)
—
y-coordinate of center point of
arc in NDC/RC units.
ptsin(2)
—
0.
ptsin (3)
—
0.
ptsin(4)
—
0.
ptsin(5)
—
0.
ptsin(6)
Radius in x-coordinate NDC/RC
units.
ptsin(7)
—
0.
Output
contrl (2) —
Number
of
output
vertices = 0
contrl (4) —
Length
of
intout
array = 0.
4-19
GEM VDI Programmer's Guide
ARC & PIE
C BINDING
Procedure Name
Data Types
Input Arguments
v_arc( handle, x, y, radius, begang, endang )
v_pieslice( handle, x, y, radius, begang,
endang )
WORD v_arc ( );
WORD handle;
WORD x, y;
WORD radius;
handle = contrl[6]
x = ptsin[0]
y = ptsin[lj
radius = ptsin[6]
begang = intin[0]
endang = intinfl]
4-20
GEM VDI Programmer's Guide
CIRCLE
CIRCLE
This function is not required and may not be
supported on all devices.
Input
contrl (0)
— —
Opcode = 11.
contrl(1)
—
Number of input vertices = 3.
contrl (3)
—
Length of intin array = 0.
contrl(5)
—
Primitive id = 4.
contrl(6)
—
Device handle.
ptsin(0)
—
x-coordinate of center point of
circle in NDC/RC units.
ptsin (1)
— —
y-coordinate of center point of
circle in NDC/RC units.
ptsin(2)
—
0 .
ptsin(3)
—
0 .
ptsin(4)
—
Radius in x-coordinate NDC/RC
units.
ptsin(5)
—
0 .
Output
contrl(2) —
Number
of
output
vertices = 0.
contrl (4) —
Length
of
intout
array = 0.
C BINDING
Procedure Name v_circle( handle, x, y, radius )
Data Types WORD v_circle ( );
WORD handle;
WORD x, y;
WORD radius;
Input Arguments handle = contrl[6]
x = ptsin[0]
y = ptsinfl]
radius = ptsin[4]
GEM VDI Programmer's Guide
ELLIPTICAL ARC and PIE
ELLIPTICAL ARC
AND PIE
Input contrl(O) —
contrl{l) —
contrl(3) —
contrl{5) —
contrl(6) —
intin(O)
intin(l)
ptsin(O)
ptsin(l)
ptsin(2)
ptsin(3)
Opcode = 11.
Number of input vertices = 2.
Length of intin array = 2.
Primitive id.
6 = ELLIPTICAL ARC
7 = ELLIPTICAL PIE SLICE
Device handle.
Start angle (in tenths of
degrees 0-3600) ,
counterclockwise.
End angle (in tenths of degrees
0-3600) .
x-coordinate of center point of
arc in NDC/RC units.
y-coordinate of center point of
arc in NDC/RC units.
Radius
units.
of
X-axis
in
NDC/RC
Radius
units.
of
Y-axis
in
NDC/RC
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
4-22
GEM VDI Programmer's Guide
ELLIPTICAL ARC and PIE
C BINDING
Procedure Name
v_ellarc( handle, x, y,
begang, endang )
xradius, yradius
v_ellpie( handle, x, y,
begang, endang )
xradius, yradius
Data Types
WORD v_ellarc ( );
WORD v ellpie ( );
WORD handle;
WORD x, y;
WORD xradius;
WORD yradius;
WORD begang;
WORD endang;
Input Arguments
handle = contrl[6]
x = ptsin[0]
y = ptsin[l]
xradius = ptsin[2]
yradius = ptsin[3]
begang = intin[0]
endang = intin[l]
4-23
GEM VDI Programmer's Guide
ELLIPSE
ELLIPSE
Input contrl(O) —
contrl(I) —
contrI(3) —
contrl(5) —
contrl(6) —
ptsin{0)
ptsin(l)
ptsin(2)
ptsin(3)
Opcode = 11.
Number of input vertices = 2.
Length of intin array = 0.
Primitive id = 5.
Device handle.
x-coordinate of center point of
ellipse in NDC/RC units,
y-coordinate of center point of
ellipse in NDC/RC units.
Radius of X-axis in NDC/RC
units.
Radius of Y-axis in NDC/RC
units.
Output
contrl{2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name v_ellipse( handle, x, y, xradius, yradius )
Data Types WORD v_ellipse ( );
WORD handle;
WORD x, y;
WORD xradius;
WORD yradius;
Input Arguments handle = contrl[6]
x = ptsin[0]
y = ptsinfl]
xradius = ptsin[2]
yradius = ptsin[3]
4-24
GEM VDI Programmer's Guide Rounded and Filled Rounded Rectangle
ROUNDED AND FILLED A rectangle with rounded corners is output to
ROUNDED RECTANGLE the workstation. The rectangle is defined by
specifying its lower left and upper right
corners.
The Rounded Rectangle GDP assumes the
attributes of a polyline primitive. The Filled
Rounded Rectangle GDP assumes the attributes of
a filled area primitive.
Input contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
ptsin(O)
ptsin(l)
ptsin(2)
ptsin(3)
Opcode = 11.
Number of input vertices = 2.
Length of intin array = 0.
Primitive id.
8 = Rounded Rectangle
9 = Filled Rounded Rectangle
Device handle.
x-coordinate of corner of
rectangle in NDC/RC units,
y-coordinate of corner of
rectangle in NDC/RC units,
x-coordinate of corner
diagonally opposite corner
selected in ptsin(O) of
rectangle in NDC/RC units,
y-coordinate of corner
diagonally opposite corner
selected in ptsin(l) of
rectangle in NDC/RC units.
Output
contr1(2)
contr1(4)
Number of output vertices =
Length of intout array = 0.
0 .
4-25
GEM VDI Programmer's Guide Rounded and Filled Rounded Rectangle
C BINDING
Procedure Name v_rbox( handle, xyarray )
v_rfbox( handle, xyarray)
Data Types
WORD ( v_rbox ) ;
WORD ( v_rfbox ) ;
WORD handle;
WORD xyarray[4];
Input Arguments handle = contrl[6];
attributes = intin[0];
xyarray[0] = ptsin[0];
xyarray[l] = ptsin[l];
xyarray[2] = ptsin[2];
xyarray[3] = ptsin[3];
4-26
GEM VDI Programmer's Guide
Justified Graphics Text
JUSTIFIED
TEXT
Input
GRAPHICS This function outputs graphics text to the
workstation display surface and attempts to
perform both left and right justification. The
text string is aligned at the requested string
alignment points passed in, using the current
text alignment attributes.
Extra spacing may be inserted or deleted by the
driver between words or characters (or both) so
that the string will have the requested length.
Either form of spacing modification (inter¬
character or inter-word) can be suppressed by
so specifying in the provided parameter.
contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
Opcode = 11.
Number of input vertices = 2.
Length of intin array = 2 + n
(characters in string).
Primitive id = 10.
Device handle.
intin(0)
intin(1)
intin(2)
Inter-word spacing flag.
0 = Doesn't allow GEM VDI to
modify inter-word spacing.
nonzero = Allows GEM VDI to
modify inter-word spacing.
Inter-character spacing flag.
0 = Doesn't allow GEM VDI to
modify inter-character spacing.
nonzero = Allows GEM VDI to
modify inter-character spacing.
First character of text string.
intin(n+1) — Last character of text string.
4-27
GEM VDI Programmer's Guide
Justified Graphics Text
ptsin(O)
x-coordinate of
the text
alignment point,
units.
in NDC/RC
ptsin(l)
y-coordinate of
the text
alignment point,
units.
in NDC/RC
ptsin(2)
Requested length of
the string,
in x-axis NDC/RC units.
ptsin(3)
0 .
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
4-28
GEM VDI Programmer's Guide
Justified Graphics Text
C BINDING
Procedure Name
Data Types
Input Arguments
v_justified(handle, x, y, string, length,
word_space, char_space);
WORD v_justified();
WORD handle;
WORD x, y;
WORD length;
WORD word_space;
WORD char_space;
BYTE string [ ];
handle = contrl[6];
x = ptsin[0];
y = ptsin[1];
length = ptsin[2];
word_space = intin[0];
char_space = intin[1];
stringtj] = intin[j+2];
Note: Bytes for the string array are mapped
into the eight least significant bits of intin
words.
Note: The string array must be null-
terminated.
End of Section 4
4-29
Section 5
Attribute Functions
INTRODUCTION
SET WRITING MODE
Attribute functions determine qualities of all
subsequent output primitives such as color,
type, style, and height.
This function selects the writing mode used for
subsequent drawing operations. The writing
mode specifies the operation performed between
the color indices of the current pixel (source)
and the existing pixel (destination), thus
affecting the way new pixels from lines,
markers, filled areas, and text are placed on
the display. Four modes exist: replace,
transparent, XOR, and reverse transparent. If
the requested writing mode is out of range, GEM
VDI selects replace mode, 1.
Table 5-1 lists the writing modes and their
numerical assignments.
Table 5-1. Writing Modes
Number
Mode
1
Replace
2
Transparent
3
XOR
4
Reverse Transparent
5-1
GEM VDI Programmer's Guide
Set Writing Mode
For the Boolean expressions of the modes given
below, the definitions in Table 5-2 apply.
Table 5-2. Terms
Term
Definition
mask
line style or fill pattern
fore
selected color after mapping from
GEM VDI
back
color 0 after mapping from GEM VDI
(white is default)
old
current color value
new
replacement color value
Replace Replace mode is insensitive to the currently
displayed image. Any information already
displayed is replaced. The following is the
Boolean expression for replace mode:
new = (fore AND mask) OR (back AND NOT mask)
Transparent Transparent mode only affects the pixels where
the mask is 1. These are changed to the fore
value. The following is the Boolean expression
for transparent mode:
new = (fore AND mask) OR (old AND NOT mask)
XOR XOR mode reverses the bits representing the
color. The following is the Boolean expression
for XOR mode:
new = mask XOR old
5-2
GEM VDI Programmer's Guide
Set Writing Mode
Reverse transparent mode only affects the
pixels where the mask is 0. These are changed
to the fore value. The following is the
Boolean expression for reverse transparent
mode:
new = (old AND mask) OR (fore AND NOT mask)
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 32.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(O)
Writing mode requested.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 1.
intout(O) —
Writing mode selected.
C BINDING
Procedure Name set_mode = vswr_mode( handle, mode )
Data Types WORD set_mode;
WORD vswr_mode ( );
WORD handle;
WORD mode;
Input Arguments handle = contrl[6]
mode = intin[0]
Output Arguments set_mode = intout[0]
Reverse
Transparent
5-3
GEM VDI Programmer's Guide
Set Color Representation
SET COLOR This function associates a color index with
REPRESENTATION the color specified in RGB (Red, Green, Blue)
units. On a monochrome device, GEM VDI maps
any percentage of color to white. GEM VDI maps
any color intensity of a value less than 0 to 0
and greater than 1000 to 1000. If the
application requests a color index that is out
of range, GEM VDI performs no operation. GEM
VDI references the background color as color
index zero.
Note: If no color lookup table exists, GEM VDI
performs no operation with this function. The
Extended Inquire function returns the
availability of the lookup table.
Input contrl(0)
contrl(l)
contrl(3)
contrl(6)
intin(0)
intin(l)
intin(2)
intin(3)
Opcode = 14.
Number of input vertices = 0.
Length of intin array = 4.
Device handle.
Color index.
Red color intensity (in tenths
of percent, 0-1000).
Green color intensity.
Blue color intensity.
Output
contrl(2)
contrl(4)
Number of
Length of
output vertices =
intout array = 0.
0 .
5-4
GEM VDI Programmer's Guide
Set Color Representation
C BINDING
Procedure Name
Data Types
Input Arguments
vs_color( handle, index, rgb_in )
WORD vs_color ( );
WORD handle;
WORD index;
WORD rgb_in[3];
handle = contrl[6]
index = intinCO]
rgb_in[0] = intin[l]
rgb__in[l] = intin[2]
rgb_in[2] = intin[3]
5-5
GEM VDI Programmer's Guide
Set Polyline Line Type
SET POLYLINE
LINE TYPE
This function sets the line type for
subsequent polyline operations. The total
number of line styles available is device¬
dependent, but all devices support at least
six. If the requested line style is out of
range, GEM VDI selects solid (1) line style.
The pixel value in the pattern word is 1 =
pixel on (active); 0 = pixel off.
16 Bits
Style MSB LSB
1 solid
2 long dash
3 dot
4 dash,dot
5 dash
6 dash,dot,dot
7 user-defined
style
8-n device¬
dependent
1111111111111111
1111111111110000
1110000011100000
1111111000111000
1111111100000000
1111000110011000
16 bits (1 word)
Most Significant
Bit = first pixel
displayed.
Line style seven, user-defined style, uses the
pattern the Set User-defined Line Style Pattern
function defines. This pattern defaults to
solid until the user defines it.
Notes If a nondefault line width is used, the
device may draw the thickened line using a
solid line style and may change the writing
mode.
5-6
GEM VDI Programmer's Guide
Set Polyline Line Type
Input
contrl(O) —
contrl(l) —
contrl(3) --
contrl(6) —
Opcode = 15.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(O)
Requested line style.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 1.
intout(O) —
Line style selected.
C BINDING
Procedure Name
set_type = vsl
_type( handle, style )
Data Types
WORD set_type
WORD vsl type
WORD handle;
WORD style?
( );
Input Arguments
handle = contrlC6]
style = intin[0]
Output Arguments set_type = intout[0]
5-7
GEM VDI Programmer's Guide
Set User-defined Line Style Pattern
SET USER-DEFINED
LINE STYLE PATTERN
This function sets the current user-defined
line style pattern word in the device driver to
the value in the specified 16-bit pattern word.
The Most Significant Bit (MSB) of the pattern
word is the first pixel in the line. This line
style is used for subsequent polyline
operations when the application selects user-
defined line style, index 7.
Input
contrl(O) — Opcode = 113.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 1.
contrl(6) — Device handle.
intin(O) — Line style pattern word, 16
bits.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name
vsl_udsty( handle, pattern )
Data Types
WORD vsl udsty ( );
WORD handle;
WORD pattern;
Input Arguments
handle = contrl[6]
pattern = intin[0]
5-8
GEM VDI Programmer's Guide
Set Polyline Line Width
SET POLYLINE LINE This function sets the width of lines for
WIDTH subsequent polyline operations. The available
line width closest to but not greater than the
requested line width is used. Line widths are
odd numbers that begin at three. If you select
two in Raster Coordinates, GEM VDI returns one,
which is a line one pixel wide.
Note: This function is not required and may
not be available on all devices. Thickened
lines may be rendered on the device using solid
line type, rather than a requested line type.
Input
contrl(O) —
Opcode = 16.
contrl(l) —
Number of input vertices = 1.
contrl(3) —
Length of intin array = 0.
contrl{6) —
Device handle.
ptsin(O)
Requested line width in x-axis
in NDC/RC units.
ptsin(l)
0 .
Output
contrl(2) —
Number of output vertices = 1.
contrl(4) —
Length of intout array = 0.
ptsout(O) —
Selected line width in x-axis of
the NDC/RC units.
ptsout(l) —
0 .
5-9
GEM VDI Programmer’s Guide
Set Polyline Line Width
C BINDING
Procedure Name
Data Types
Input Arguments
set width = vsl_width( handle, width )
WORD set_width;
WORD vsl_width?
WORD handle;
WORD width?
handle = contrl[6]
width = ptsin[0]
set_width = ptsout[0]
Output Arguments
GEM VDI Programmer's Guide
Set Polyline Color Index
SET POLYLINE This function sets the color index for
COLOR INDEX subsequent polyline operations. The Set Color
Representation function determines the color
the index represents. At least two color
indices, 0 and 1, are supported (monochrome).
Color indices range from 0 to a device¬
dependent maximum. If the application requests
an index that is out of range, GEM VDI selects
color index 1.
Input contrl(O) — Opcode = 17.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 1.
contrl{6) — Device handle.
intin(O) — Requested color index.
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 1.
intout(O) — Color index selected.
C BINDING
Procedure Name set_color = vsl_color( handle, color_index )
Data Types WORD set_color;
WORD vsl_color ( );
WORD handle;
WORD color index;
Input Arguments handle = contrl[6]
color_index = intinCO]
Output Arguments set_color = intout[0]
5-11
GEM VDI Programmer's Guide
Set Polyline End Styles
SET POLYLINE END This function sets the style for the ends of
STYLES a polyline. The style may be any of the
following:
0 - squared (default)
1 - arrow
2 - rounded
The two ends of a polyline may have different
styles. If an invalid style is requested, a
squared end style (0) is used.
Both the squared style and the arrow style end
at the end of the polyline. The rounded style
is drawn such that the center of the rounding
is at the end of the polyline.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 108.
Number of input vertices = 0.
Length of intin array = 2.
Device handle.
intin(0)
intin(l)
End style for beginning point of
polyline.
0 - squared (default)
1 - arrow
2 - rounded
End style for ending point of
polyline.
0 - squared (default)
1 - arrow
2 - rounded
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 0.
5-12
GEM VDI Programmer's Guide
Set Polyline End Styles
C BINDING
Procedure Name vsl_ends( handle, beg_style, end_style )
Data Types WORD vsl_ends();
WORD handle;
WORD beg_style;
WORD end_style;
Input Arguments handle = contrl[6]?
beg_style = intin[0];
end_style = intin[l];
5-13
GEM VDI Programmer's Guide
Set Polymarker Type
SET POLYMARKER This function sets the marker type for
TYPE subsequent polymarker functions. The total
number of markers available is device¬
dependent, but GEM VDI always defines at least
six marker types:
1
2
3
4
5
6
7
- +
_ *
- 0
- X
- <>
Dot
Plus
Asterisk
Square
Diagonal Cross
Diamond
Device-dependent
If the requested marker type is out of range,
GEM VDI uses an asterisk, type 3. Marker 1 is
the smallest dot GEM VDI displays on the
device; it cannot be scaled.
Input
contrl(0)
contr1(1)
contrl(3)
contrl(6)
Opcode = 18.
Numbers of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(0)
Requested polymarker type.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 1.
intout(O) — Polymarker type selected.
5-14
GEM VDI Programmer's Guide
Set Polymarker Type
C BINDING
Procedure Name
Data Types
Input Arguments
set_type = vsm_type( handle, symbol )
WORD set_type;
WORD vsm_type ( );
WORD handle;
WORD symbol;
handle = contrl[6]
symbol = intin[0]
Output Arguments set_type = intout[0]
GEM VDI Programmer's Guide
Set Polymarker Height
SET POLYMARKER This function sets a polymarker height for
HEIGHT subsequent polymarker functions. If the
selected height does not exist, GEM VDI selects
the next smaller height. The driver returns
the actual height selected in the ptsout array.
Input contrl(O) — Opcode = 19.
contrl(l) — Number of input vertices = 1.
contrl(3) — Length of intin array = 0.
contrl(6) — Device handle.
ptsin(O) — 0.
ptsin(l) — Requested polymarker height in
y-axis in NDC/RC units.
Output contrl(2) — Number of output vertices = 1.
contrl(4) — Length of intout array = 0.
ptsout(O) — Polymarker width selected in x-
axis in NDC/RC units.
ptsout(l) — Polymarker height selected in y-
axis in NDC/RC units.
C BINDING
Procedure Name set_height = vsm_height( handle, height )
Data Types WORD set_height;
WORD vsm_height ( )?
WORD handle?
WORD height?
Input Arguments handle = contrl[6]
height = ptsin[l]
Output Arguments set_height = ptsout[l]
5-16
GEM VDI Programmer's Guide
Set Polymarker Color Index
SET POLYMARKER
COLOR INDEX
This function sets the color index for
subsequent polymarker functions. The Set Color
Representation function specifies the value of
the index. At least two color indices are
always supported (monochrome). If the index is
out of range, GEM VDI selects color index 1.
Input
contrl(O) —
contrl(l) —
contrl{3) —
contrl(6) —
Opcode = 20.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(O)
Requested polymarker color
index.
Output
contrl(2) —
contrl(4) —
number of output vertices = 0.
length of intout array = 1.
intout(O) —
Polymarker color index selected.
C BINDING
Procedure Name
set color = vsm color( handle, color index )
Data Types
WORD set_color;
WORD vsm_color ( );
WORD handle;
WORD color index;
Input Arguments handle = contrl[6]
color index = intin[0]
Output Arguments set color = intout[0]
5-17
GEM VDI Programmer's Guide
Set Character Height, Absolute Mode
This function sets the current graphic text
character height in NDC/RC units. The
specified height is the distance from the
character baseline to the top of the character
cell, rather than the character cell height.
GEM VDI returns the selected height and width
information to the application. GEM VDI
returns both the distance from the baseline to
top line selected and the size of a character
cell. (See Figure 5-1 under "Set Character
Height, Points Mode.") For fixed (monospaced)
faces GEM VDI returns the width of a character
and the width of a character cell. For
proportional faces, GEM VDI returns the width
of the widest character and the width of the
widest character cell in the face.
If the desired character height does not map
exactly to a device size, GEM VDI selects the
closest character size that does not exceed the
requested size.
SET CHARACTER
HEIGHT,
ABSOLUTE MODE
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 12.
Number of input vertices = 1.
Length of intin array = 0.
Device handle.
ptsin(O)
0 .
ptsin(l)
Requested character height in
NDC/RC units.
Output
contrl(2) —
Number of output vertices = 2.
contrl(4) —
Length of intout array = 0.
ptsout(O) —
Character width selected in
NDC/RC units.
ptsout(l) —
Character height selected in
NDC/RC units.
ptsout(2) —
Character cell width in NDC/RC
units.
ptsout(3) —
Character cell height in NDC/RC
units.
5-18
GEM VDI Programmer's Guide
Set Character Height, Absolute Mode
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vst_height( handle, height, &char_width,
&char_height, &cell_width, &cell_height )
WORD vst_height ( );
WORD handle;
WORD height;
WORD char_width;
WORD char_height;
WORD cell_width;
WORD cell_height;
handle = contrl[6]
height = ptsin[l]
char_width = ptsout[0]
char_height = ptsout[l]
cell_width = ptsout[2]
cell_height = ptsout[3]
5-19
GEM VDI Programmer's Guide
Set Character Height, Points Mode
SET CHARACTER CELL
HEIGHT, POINTS
MODE
Input
This function sets the current graphic text
character height in printer points. A point
is l/72 of an inch. The specified height is the
distance between the baseline of one line of
text and the baseline of the next line of text,
which is the character cell height.
The driver returns the selected point size of
the character. Height and width information is
returned in NDC/RC units. GEM VDI returns the
character height, character width, cell height,
and the cell width, as shown in Figure 5-1.
For proportional faces, GEM VDI returns the
width of the widest character and the widest
character cell in the face.
If the desired character height does not map
exactly to a device size, GEM VDI selects the
closest character size not exceeding the
requested size.
Left Character Right Character
Alignment Alignment
Delta Delta
* '
_
Character
Height
w
Character
Width
Cell
Width
Figure 5-1. Character Cell Definition
contrl(0)
contrl(l)
contrl(3)
contrl(6)
Opcode = 107.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(0)
Cell height in points.
5-20
GEM VDI Programmer's Guide
Set Character Height, Points Mode
Output
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
contrl(2) — Number of output vertices = 2.
contrl(4) — Length of intout array = 1.
intout(O) — Selected cell height in points.
ptsout(O) —
ptsout(l) —
ptsout(2) —
ptsout(3) —
Character width selected in
NDC/RC units.
Character height selected in
NDC/RC units.
Character cell width in NDC/RC
units.
Character cell height in NDC/RC
units.
set_j?oint = vst_jpoint( handle, point,
&char_width, &char__height, &cell_width,
&cell_height )
WORD set_point;
WORD vst_point( );
WORD handle;
WORD point;
WORD char_width;
WORD char_height;
WORD cell_width;
WORD cell_height;
handle = contrl[6]
point = intin[0]
set_point( ) = intout[0]
char_width = ptsout[0]
char_height = ptsoutCl]
cell_width = ptsout[2]
cell_height = ptsout[3]
5-21
GEM VDI Programmer's Guide
Set Character Baseline Vector
SET CHARACTER This function requests an angle of rotation
BASELINE VECTOR specified in tenths of degrees for the character
baseline vector, which specifies the baseline
for subsequent graphic text. The driver
returns the selected baseline vector to the
application. The selected baseline vector is a
best-fit match to the requested value.
See Figure 5-2 for a depiction of how angles
are specified to GEM VDI.
900
1800 - 0
2700
Figure 5-2. Angle Specification
Notes This function is not required and may
not be supported on all devices. The Extended
Inquire function returns the availability of
this function.
Input
contrl(0)
contrl(1)
contrl(3)
contrl(6)
Opcode = 13.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(O) — Requested angle of rotation of
character baseline (in tenths
of degrees, 0 - 3600).
Output
contrl(2)
contrl(4)
intout(0)
Number of output vertices = 0.
Length of intout array = 1.
Angle of rotation of character
baseline selected (in tenths of
degrees 0-3600).
5-22
GEM VDI Programmer's Guide
Set Character Baseline Vector
C BINDING
Procedure Name set_baseline = vst_rotation( handle, angle )
Data Types WORD set_baseline;
WORD vst_rotation ( ) ;
WORD handle;
WORD angle;
Input Arguments handle = contrl[6]
angle = intinCO]
Output Arguments set_baseline = intout[0]
5-23
GEM VDI Programmer's Guide
Set Text Face
SET TEXT FACE This function selects a graphic character face
for subsequent graphic text operations. Face 1
is a built-in face. The other faces are
external and may be loaded with the Load Face
function. Some faces may not be supported on
all devices. Face names and indices may be
determined by using Inquire Face Name.
Opcode = 21.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
Requested software text face
number.
1 - System face
2 - Swiss 721
3 - Swiss 721 Thin
4 - Swiss 721 Thin Italic
5 - Swiss 721 Light
6 - Swiss 721 Light Italic
7 - Swiss 721 Italic
8 - Swiss 721 Bold
9 - Swiss 721 Bold Italic
10 - Swiss 721 Heavy
11 - Swiss 721 Heavy Italic
12 - Swiss 721 Black
13 - Swiss 721 Black Italic
14 - Dutch 801 Roman
15 - Dutch 801 Italic
16 - Dutch 801 Bold
17 - Dutch 801 Bold Italic
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 1.
intout(0) — Text face selected.
Input contrl(0)
contrl(1)
contrl(3)
contrl(6)
intin(0)
5-24
GEM VDI Programmer's Guide
Set Text Face
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
set_font = vst_font( handle, font )
WORD set_font;
WORD vst_font ( );
WORD handle?
WORD font?
handle = contrl[6]
font = intin[0]
set font = intout[0]
5-25
GEM VDI Programmer's Guide
Set Graphic Text Color Index
SET GRAPHIC TEXT This function sets the color index for
COLOR INDEX subsequent graphic text operations. The Set
Color Representation function determines the
color represented by the color index. All
devices support at least two color indices, 0
and 1 (monochrome). Color indices range from 0
to a device-dependent maximum. If the
requested index is out of range, GEM VDI
selects color index 1.
Input
contrl(0)
contr1(1)
contr1(3)
contrl(6)
Opcode = 22.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(0)
Requested text color index.
Output
contrl(2) — Number of output vertices = 0.
contr1(4) — Length of intout array = 1.
intout(O) — Text color index selected.
C BINDING
Procedure Name set_color = vst_color( handle, color_index )
Data Types
WORD set_color?
WORD vst_color ( );
WORD handle;
WORD color index;
Input Arguments
handle = contrl[6]
color_index = intin[0]
Output Arguments
set color = intout[0]
5-26
GEM VDI Programmer's Guide
Set Graphic Text Special Effects
SET GRAPHIC TEXT
SPECIAL EFFECTS
This function sets text special effects for
subsequently displayed graphic text. The
following effects are available:
• thickened
• light intensity
• skewed
• underlined
• outlined
• shadowed
• any combination of the above
GEM VDI treats the integer in intin (0) as a bit
pattern. The attributes set correspond to the
setting in the six least significant bits.
Table 5-3. Attribute Bit Mapping
Bit
Value
Description
0
Thickened
0
thickened not selected
1
set style to thickened
1
Intensity
0
normal intensity
1
light intensity
2
Skewed
0
skewed not selected
1
set style to skewed
3
Underlined
0
do not underline
1
text is underlined
4
Outline
0
no outline
1
outline
5
Shadow
0
no shadow
1
shadow
5-27
GEM VDI Programmer's Guide
Set Graphic Text Special Effects
For example, if intin(O) = 9 (1001 binary), the
text style is set to thickened and underlined.
For effects not supported on a device, GEM VDI
returns those bits set to 0.
Input
contrl(0)
contrl(l)
contrl( 3 )
contrl(6)
Opcode = 106.
— Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(0)
Special effect word.
Number of output vertices = 0.
— Length of intout array = 1.
— Styles actually selected (style
word with the appropriate bits
set).
Normal
Thickened
Light Intensity
Skewed
Underlined
Figure 5-3. Graphic Text Special Effects
ABCDE
ABODE
a o r\ r~
^ I' I .? f ; I "
® li mmmm
ABODE
ABCDE
Output contrl(2)
contrl(4)
intout(0)
5-28
GEM VDI Programmer's Guide
Set Graphic Text Special Effects
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
set_effect = vst_effects( handle.
WORD set_effect;
WORD vst_effects( );
WORD handle?
WORD effect;
handle = contrl[6]
effect = intin[0]
set_effect = intout[0]
effect )
5-29
GEM VDI Programmer's Guide
Set Graphic Text Alignment
SET GRAPHIC
ALIGNMENT
TEXT This function sets horizontal and vertical
alignment for graphic text. Horizontal means in
the direction of the baseline? vertical is
perpendicular to the baseline. This function
controls the positioning of the text string in
relation to the graphic text position. The
default alignment places the left baseline
corner of the string at the graphic text
position.
If the application requests an invalid
horizontal alignment, GEM VDI selects the
default, left. If the application requests an
invalid vertical alignment, GEM VDI selects the
default, baseline.
Leading
Tod Line
Ascent Line
a ~*~r
Half Line
AlgTL
Base Line
_^_
Bottom Line Tod Line
Ascent Line
Half Line
This
Base Line
Descent Line
Bottom Line
Figure 5-4. Graphic Text Alignment
5-30
GEM VDI Programmer's Guide
Set Graphic Text Alignment
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 39.
Number of input vertices =0.
Length of intin array = 2.
Device handle.
intin(O) —
Horizontal alignment requested.
0 = left justified (default)
1 = center justified
2 = right justified
intin(l)
Vertical alignment requested.
0 = baseline (default)
1 = half line
2 = ascent line
3 = bottom
4 = descent
5 = top
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 2.
intout(O) —
intout(1) —
Horizontal alignment selected.
Vertical alignment selected.
C BINDING
Procedure Name vst_alignment( handle, hor_in, vert__in,
&hor_out, &vert_out )
Data Types WORD vst_alignment( );
WORD handle;
WORD hor_in;
WORD vert_in;
WORD hor_out;
WORD vert out;
Input Arguments handle = contrl[6]
hor_in = intin[0]
vert_in = intin[l]
Output Arguments hor_out = intout[0]
vert out = intout[l]
5-31
GEM VDI Programmer's Guide
Set Fill Interior Style
SET FILL INTERIOR
STYLE
This function sets the fill interior style
used in subsequent polygon fill operations. If
the application requests an unavailable style,
the area is hollow filled. GEM VDI returns the
selected style to the application. Hollow
style fills the interior with the current
background color(index 0). Solid style fills
the area with the currently selected fill
color.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 23.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(O)
Requested fill interior style.
0 - hollow
1 - solid
2 - pattern
3 - hatch
4 - user-defined style
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 1.
intout(O) —
Fill interior style selected.
C BINDING
Procedure Name set_interior = vsf_interior( handle, style )
Data Types
WORD set_interior;
WORD vsf_interior ( )
WORD handle;
WORD style;
Input Arguments handle = contrl[6]
style = intinCO]
Output Arguments set_interior = intout[0]
5-32
GEM VDI Programmer's Guide
Set Fill Style Index
SET FILL
INDEX
STYLE This function selects a fill style based on
the fill interior style. This index has no
effect if the interior style is hollow, solid,
or user-defined. Indices range from 1 to a
device-dependent maximum. If the requested
index is not available, GEM VDI uses index
style 1. The index references a hatch style if
the selected fill interior style is hatch, or a
pattern if the selected interior fill style is
pattern.
Figure 5-5 shows the available fill styles.
Under each rectangle in Figure 5-5 are two
numbers, separated by a comma. The number to
the left of the comma corresponds to the style:
Hollow, Pattern, or Hatch. The number to the
right of the comma corresponds to the index for
the particular pattern or hatch.
0,n
iYiYiViW
2,1
miiiimnutiii
2,2
t fy'i iSui'yV
VVt^Vtx'W
2,3
Bill
2,4
ws.
2,5
2,6
2,7
Bsgf;
2,8
2,9
2,10
A ’’’ ■'
2,11
T7TTTTT7T
2,12
'/
2,13
i* i'.'
2,14
2,15
2,16
2,17
’ 2,18
2,19
W':
2,20
A A.~
2,21
II llllltMlIMHIl
2,22
.
2,23
■Hi
2,24
'&///.
3,1
7777 /
3,2
TO
3,3
mm
3,4
1 1
3,5
1 t 1 1
3,6
/ /
3,7
szn
3,8
3,10
3,11
3,12
Figure 5-5. Fill Styles and Indices
5-33
GEM VDI Programmer’s Guide
Set Fill Style Index
Note: l,n (i.e., Style 1 , followed by any
index) produces the same result as 2,8.
For patterns, index 1 maps to the lowest
intensity pattern on the device. The pattern
is always monochrome and uses the current fill
area color for foreground pixels.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 24.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(O)
Requested fill style index for
pattern or hatch fill.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 1.
intout(O) —
Fill style index selected for
pattern or hatch fill.
C BINDING
Procedure Name set_style = vsf_style( handle, style_index )
Data Types
WORD set_style;
WORD vsf_style ( );
WORD handle;
WORD style_index;
Input Arguments
handle = contrl[6]
style_index = intin[0]
Output Arguments set_style = intout[0]
5-34
GEM VDI Programmer's Guide
Set Fill Color Index
SET FILL COLOR This function sets the color index for
INDEX subsequent polygon fill functions. The Set
Color Representation function determines the
color represented by the color index. All
devices support at least two color indices, 0
and 1 (monochrome). Color indices range from 0
to a dev ice-dependent maximum. If the
requested index is out of range, GEM VDI
selects color index 1.
Input contrl(O) — Opcode = 25.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 1.
contrl(6) — Device handle.
intin(O) — Requested fill color index.
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 1.
intout(O) — Fill color index selected.
C BINDING
Procedure Name set color = vsf_color( handle, color_index )
Data Types WORD set_color;
WORD vsf_color ( );
WORD handle;
WORD color index?
Input Arguments handle = contrl[6]
color index = intin[0]
Output Arguments set_color = intout[0]
5-35
GEM VDI Programmer's Guide
Set Fill Perimeter Visibility
SET FILL PERIMETER
VISIBILITY
This function turns the outline of a fill
area on or off. When visibility is on (the
default at Open Workstation) the border of a
fill area is drawn in the current fill area
color with a solid line. When visibility is
off, no outline is drawn. Any nonzero value of
the visibility flag causes the perimeter to be
vis ible.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 104.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(O)
Visibility flag.
zero - invisible
nonzero - visible
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 1.
intout(O) —
Visibility selected.
C BINDING
Procedure Name
set_perimeter = vsf_perimeter( handle, per_vis
Data Types
WORD set perimeter;
WORD vsf_perimeter ( )
WORD handle;
WORD per_vis;
Input Arguments
handle = contrl[6]
per_vis = intin[0]
Output Arguments set_j?erimeter = intout[0]
5-36
GEM VDI Programmer's Guide
Set User-defined Fill Pattern
SET USER-DEFINED This function redefines the user-definable
FILL PATTERN fill pattern.
For the pattern data, bit 15 of word 1 is the
upper left bit of the pattern. Bit 0 of word
16 is the lower right bit of the pattern. Bit
zero is the Least Significant Bit of the word.
Words are stored in the same format as 16-bit
integers
For a single plane pattern, a bit value of 1
indicates foreground color. A bit value of 0
indicates the background color. The color used
for the foreground is determined by the current
fill area color index.
For a multiple plane pattern, the number of
full 16-by-16 planes defined are used in the
fill operation: planes = contrl(3) / 16. Any
unspecified planes are zeroed. Note that the
writing mode must be set to replace (mode 1),
when using a multiplane fill pattern.
The defined pattern is referenced by the Set
Fill Interior Style function as style 4 and by
the Fill Rectangle function.
Input contrl(O) — Opcode = 112.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 16 to n.
contrl(6) — Device handle.
intin(O) to
intin(15) — First plane of fill pattern.
intin(16) to
intin(29) — Second plane of fill pattern.
intin(n-15) to
intin(n) — Last plane of fill pattern.
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
5-37
GEM VDI Programmer's Guide
Set User-defined Fill Pattern
C BINDING
Procedure Name
Data Types
Input Arguments
vsf_udpat( handle, pfill_pat, planes )
WORD vsf_udpat;
WORD handle;
WORD pfill_pat[16 x n where n > 0]
WORD planes;
handle = contrl[6]
pfill_
pfill pat
planes = contrl[3]/l6
End of Section 5
5-38
Section 6
Raster Operations
INTRODUCTION
MEMORY FORM
DEFINITION BLOCK
Raster operations perform logic operations on
rectangular blocks of bits in memory and on
rectangular blocks of pixels on physical
devices.
A raster area is defined by a Memory Form
Definition Block (MFDB). An MFDB consists of
the following components:
• A 32-bit pointer to the memory address of the
upper left corner of the first plane of the
raster area. This pointer corresponds to an
offset-segment pointer for 8086-based
microcomputers. If all 32 bits of this
pointer are 0, the MFDB is for a physical
device, and the other parameters are ignored.
• The height and width of the raster area in
pixels.
• The width of the raster area in words. This
value is equal to the width of the raster
area in pixels, divided by the word size.
• The number of planes in the raster area.
• A flag indicating whether the format of the
raster area is standard or device-dependent.
• Some locations reserved for future use.
A raster area must start on a word boundary and
have a width that is an integral multiple of
the word size-
6-1
GEM VDI Programmer's Guide
Memory Form Definition Block
RASTER AREA
FORMATS
Word 1
Word 2
Word 3
Word 4
Word 5
Word 6
Word 7
Word 8
Word 9
Word 10
Figure 6-1. Memory Form Definition Block
One word (16 bits)
Memory pointer word 1
Memory pointer word 2
Form Width in Pixels
Form Height in Pixels
Form Width in Words
Form format flag
Number of Memory Planes
Reserved for future use
Reserved for future use
Reserved for future use
Two memory formats are associated with raster
areas:
• device-specific format
• well-defined standard format
GEM VDI provides a function to transform a
raster area from one format to another. You
must transform a form before using Copy Raster.
The form format flag can have two values:
0 - The form is in device-specific format.
1 - The form is in standard format.
The layout of a standard form format is as
follows (see also Figure 6-2):
6-2
GEM VDI Programmer's Guide
Raster Area Formats
• Plane based - The planes are contiguous
blocks of memory, each having the same x,y
resolution. A monochrome implementation has
a single plane. A color index is mapped to a
pixel value with each plane representing one
bit in the value. Tables 6-1 and 6-2 define
the pixel-value-to-color-index mapping for
eight-color and sixteen-color screens,
respectively.
• Most Significant Bit in a word (16-bit
integer) is the leftmost bit in the image.
Note that the data is stored in the same
format as 16-bit integers.
• Words are arranged sequentially along a row
with the first word being on the left edge of
the row.
Table 6-1. Pixel Value to Color Index
Mapping for 8-color Screens
Pixel Value
Color Index
Color
0
white
2
red
010
3
green
Oil
6
yellow
4
blue
101
7
magenta
110
5
cyan
111
1
black
6-3
GEM VDI Programmer's Guide
Raster Area Formats
Table 6-2. Pixel Value to Color Index
Mapping for 16-color Screens
Pixel Value
Color Index
Color
0000
0
white
0001
2
red
0010
3
green
0011
6
yellow
0100
4
blue
0101
7
magenta
0110
5
cyan
0111
8
low white
1000
9
grey
1001
10
light red
1010
11
light green
1011
14
light yellow
1100
12
light blue
1101
15
light magenta
1110
13
light cyan
1111
1
black
Note: A pixel value of 0 maps to the
background color.
In addition to the MFDB, Copy Raster also takes
a rectangle as an argument. This allows
operations on a specified portion of the raster
area. A rectangle is specified by the x,y
coordinates of its upper left and lower right
vertices.
COORDINATE SYSTEMS A sample single-plane memory form with a form
width of 16 pixels, a form height of 8 pixels,
and a highlighted rectangle with corners of
(3,1) and (6,5) is shown in Figure 6-3.
6-4
GEM VDI PRogrammer's Guide
Coordinate Systems
GEM VDI PRogrammer's Guide
Logic Operations
1AGIC OPERATIONS To provide greatest flexibility, raster
operations subject to a logic operation take
the operation as an argument rather than using
the logic operation associated with vector
primitives. In addition, the operations
available are greatly expanded to allow more
flexibility. Table 6-3 lists the available
operations with the following conventions:
• S = pixel value (0 or 1) of source pixel
• D = pixel value (0 or 1) of destination pixel
• D'= destination pixel value after the logical
operation
Table 6-3. Raster Operation
Logic Operations
Mode
Definition
0
D 1 = 0
1
D'= S AND D
2
D'= S AND [NOT D]
3
D'= S ( Replace mode )
4
D' = [NOT S] AND D ( Erase mode )
5
D' = D
6
D'= S XOR D ( XOR mode )
7
D'= S OR D
8
D'= NOT [S OR D]
9
D'= NOT [S XOR D]
10
D'= NOT D
11
D'= S OR [NOT D]
12
D 1 = NOT S
13
D'= [NOT S] OR D
14
D'= NOT [S AND D]
15
D’= 1
6-6
GEM VDI Programmer's Guide
Copy Raster, Opaque
COPY RASTER,
OPAQUE
Input
This function copies a rectangular raster
area from source form to destination form using
the logic operation the application specifies.
If the source and destination forms are the
same, and the rectangles overlap, GEM VDI
copies so that the source rectangle is not
changed until GEM VDI processes the
corresponding area in the destination. No
rotation or transformation occurs as a result
of this function; the copy is pixel for pixel.
If the source and destination rectangles are
not the same size, GEM VDI uses the destination
as a pointer and uses the source for the size.
The Extended Inquire function returns scaling
ability. The source and destination forms must
be in device-specific form; see "Transform
Form" later in this section.
contrl(O) — Opcode = 109.
contrl(l) — Number of input vertices = 4.
contrl(3) — Length of intin array = 1.
contrl(6) — Device handle.
contrl(7-8)— Double-word address of the
source Memory Form Definition
Block.
contr 1( 9-10) - Double-word address of the
destination Memory Form
Definition Block.
intin(O)
ptsin(O)
ptsin{l) —
ptsin{2) —
ptsin(3) —
Logic operation (refer to
"Introduction" in this
section).
x-coordinate of corner of source
rectangle in RC/NDC.
y-coordinate of corner of source
rectangle in RC/NDC.
x-coordinate of corner
diagonally opposite corner
selected in ptsin(O) of source
rectangle in RC/NDC.
y-coordinate of corner
diagonally opposite corner
selected in ptsin(l) of source
rectangle in RC/NDC.
6-7
GEM VDI Programmer's Guide
ptsin(4)
ptsin(5)
ptsin(6)
ptsin(7)
Copy
Raster, Opaque
x-coordinate
of corner
of
destination
rc/ndc.
r e c tangle
in
y-coordinate
of corner
of
destination
RC/NDC.
r e c tangle
i n
x-coordina te
of corner
of
de s t ina t ion
RC/NDC.
r ec tangle
i n
y-coordinate
of corner
of
destination
RC/NDC.
r ec tangle
i n
Output
contrl(2) — Number of output vertices = 0.
contrl{4) — Length of intout array = 0.
C BINDING
Procedure Name vro_cpyfm( handle, wr_mode, pxyarray,
psrcMFDB, pdesMFDB )
Data Types WORD vro_cpyfm ( );
WORD handle 7
WORD wr_mode 7
WORD pxyarray[8]7
WORD *psrcMFDB 7
WORD *pdesMFDB 7
Input Arguments handle = contrl[6]
wr_mode = intin[0]
pxyarrayCO] = ptsin[0]
pxyarrayCl] = ptsin[l]
pxyarray[7] = ptsin[7]
psrcMFDB = contrl[7-8]
pdesMFDB = contrl[9-10]
6-8
GEM VDI Programmer's Guide
Copy Raster, Transparent
COPY RASTER,
TRANSPARENT
This function copies a monochrome rectangular
raster area from source form to a color area. A
writing mode and color indices for both 0's and
l's are specified in the intin array.
If the source and destination rectangles are
not the same size, GEM VDI uses the source
rectangle for the size and the upper left
corner of the destination rectangle for the
initial destination location.
Transfer of information from the source to the
destination is controlled by the specified
writing mode as described below. See Table 5-1
for a binding of the available writing modes.
Replace Mode
Replace mode will result in a replacement of all
pixels in the destination rectangle. The
foreground color index specified in intin(l)
will be output to all pixels associated with
source locations which are set to a one. The
background color index specified in intin(2)
will be output to all pixels associated with
source locations which are set to a zero.
Transparent Mode
Transparent mode only affects the pixels
associated with a source value of one. Those
pixels are set to the foreground color whose
index is specified in intin(l). The color
index specified in intin(2) is not used.
XOR Mode
In XOR mode, the monochrome raster source area
is logically XORed with each plane of the
destination. The color indices specified in
intin(l) and intin(2) are not used.
6-9
GEM VDI Programmer's Guide
Copy Raster, Transparent
Reverse
Transparent
Mode
Reverse Transparent mode only affects the
pixels associated with a source value of
zero. Those pixels are set to the background
color whose index is specified in intin(2).
The color index specified in intin(l) is not
used.
Input
Opcode = 121.
Number of input vertices = 4.
Length of intin array = 3.
Device handle.
Double-word address of the
source Memory Form Definition
Block.
Double-word address of the
destination Memory Form
Definition Block.
Writing Mode.
Color index for Is in data.
Color index for Os in data.
x-coordinate of corner of source
rectangle in RC/NDC.
y-coordinate of corner of source
rectangle in RC/NDC.
x-coordinate of corner
diagonally opposite corner
selected in ptsin(O) of source
rectangle in RC/NDC.
y-coordinate of corner
diagonally opposite corner
selected in ptsin(l) of source
rectangle in RC/NDC.
contrl(O) —
contrl(l) —
contrl(3) —
contrl{6) —
contrl(7-8)—
contr1(9-10) -
intin(O)
intin(l)
intin{2) —
ptsin(O)
ptsin(l)
ptsin(2)
ptsin{3)
ptsin(4) —
ptsin(5)
ptsin(6) —
ptsin(7)
x-coordinate
destination
RC/NDC.
y-coordinate
de s tination
RC/NDC.
x-coordinate
de s tination
RC/NDC.
y-coordinate
destination
RC/NDC.
of corner
of
r e c tangle
in
of corner
of
rectangle
in
of corner
of
rec tangle
i n
of corner
of
rec tangle
in
6-10
GEM VDI Programmer's Guide
Copy Raster, Transparent
Output
C BINDING
Procedure Name
Data Types
Input Arguments
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
vrt_cpyfm( handle, wr_mode, pxyarray,
psrcMFDB, pdesMFDB, color_index )
WORD vrt_cpyfm ( );
WORD handle;
WORD wr_mode;
WORD pxyarray[8];
WORD *psrcMFDB;
WORD *pdesMFDB;
WORD color index[2];
handle = contrl[6]
wr_mode = intin[0]
pxyarrayCO] = ptsin[0]
pxyarrayCl] = ptsin[l]
pxyarray[7] = ptsin[7]
psrcMFDB = contrl[7-8]
pdesMFDB = contrl[9-10]
color_index[03 = intin[l]
color_index[lD = intin[2]
6-11
GEM VDI Programmer's Guide
Transform Form
TRANSFORM FORM
This function transforms a raster area from
standard format to device-specific format or
from device-specific to standard format. The
operation is a toggle, changing the current
state.
The number of planes specified in the source
MFDB determines the number transformed. The
source format flag is toggled and placed in the
destination. The user is required to ensure
that the other parameters in the destination
MFDB are correct.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
contrl(7-8) —
contrl(9-10) -
Opcode = 110.
Number of input vertices = 0.
Length of intin array = 0.
Device handle.
Double-word address of the
source MFDB.
Double-word address of the
destination MFDB.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 0.
C BINDING
Procedure Name vr_trnfm( handle, psrcMFDB, pdesMFDB )
Data Types WORD vr_trnfm ( );
WORD handle?
WORD *psrcMFDB?
WORD *pdesMFDB;
Input Arguments handle = contrl[6]
psrcMFDB = contrl[7-8]
pdesMFDB = contrl[9-10]
6-12
GEM VDI Programmer's Guide
Get Pixel
GET PIXEL
This function returns a pixel value and a color
index for the pixel specified by ptsin(O),
ptsin(1).
Note: Color index 0 is the background color.
It may or may not map to pixel value 0 in
device-specific form. Refer to Tables 6-1 and
6-2 for the colors and values. Standard form
always maps color index 0 to pixel value 0.
Input
contrl(O) — Opcode = 105.
contrl(1) — Number of input vertices = 1.
contrl(3) — Length of intin array = 0.
contrl(6) — Device handle.
ptsin(0) — x-coordinate of pixel in RC/NDC
units.
ptsin(1) — y-coordinate of pixel in RC/NDC
units.
Output
contr1(2)
contrl (4)
Number of output vertices = 0.
Length of intout array = 2.
intout(0) — Pixel value,
intout(1) — Color index.
GEM VDI Programmer's Guide
Get Pixel
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
v_get_j?ixel( handle, x, y, pel, index )
WORD v get pixel( );
WORD handle;
WORD x;
WORD y;
WORD *pel;
WORD *index;
handle = contrl[6]
x = ptsin[0]
y = ptsinCl]
pel = intout[0]
index = intout[l]
End of Section 6
6-14
Section 7
Input Functions
INTRODUCTION The input functions allow user interactions with
the application program. Many of the input
functions support two modes: request and
sample. In request mode, the driver waits
until an input event occurs before returning.
In sample mode, the driver returns the current
status or location of the input device without
waiting.
SET INPUT MODE This function sets the input mode for the
following specified logical input devices to
request or sample:
• locator
• valuator
• choice
• string
Select the input mode in intin(l).
Input contr1(0) — Opcode = 33.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 2.
contrl(6) — Device handle.
intin(O) — Logical input device.
1 = locator
2 = valuator
3 = choice
4 = string
intin(l) — Input mode.
1 = request
2 = sample
7-1
GEM VDI Programmer's Guide
Set Input Mode
Output
C BINDING
Procedure Name
Data Types
Input Arguments
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 1.
intout(O) — Input mode selected.
vsin_mode( handle, dev_type, mode )
WORD vsin_mode ( );
WORD handle;
WORD dev_type;
WORD mode;
handle = contrl[6]
dev_type = intin[0]
mode = intin[l]
7-2
GEM VDI Programmer's Guide
Input Locator, Request Mode
INPOT LOCATOR, This function returns the position of the
REQUEST MODE specified locator device. Upon entry to the
locator routine, the current cursor form is
displayed at the initial coordinate. The
graphic cursor is tracked with the input device
until a terminating event occurs, which can
result from the user pressing a key or a button
on a mouse. GEM VDI removes the cursor when
the terminating event occurs. Typically, the
arrow keys move the cursor in large jumps when
used without the Shift key and in pixel
increments when used with the Shift key.
This function always displays a cursor on the
screen, even if the cursor is currently
obscured or hidden.
Note: If both a keyboard and another locator
device are available, the cursor is tracked by
input from either, giving the user maximum
flexibility.
Input
contrl(O) —
Opcode = 28.
contrl(l) —
Number of input vertices = 1.
contrl(3) —
Length of intin array = 0.
contrl(6) —
Device handle.
ptsin(O)
Initial x-coordinate of locator
in NDC/RC units.
ptsin(l)
Initial y-coordinate of locator
in NDC/RC units.
7-3
GEM VDI Programmer's Guide
Input Locator, Request Mode
Output contrl(2) —
contrl(4) —
intout(O) —
ptsout(O) —
ptsout(l) —
Number of output vertices = 1.
Length of intout array = 1.
Locator terminator.
The low byte contains a
character terminator. For
keyboard-terminated locator
input, this is the ASCII
character code of the key
struck to terminate input. For
nonkeyboard-terminated input
(tablet, mouse, and so on),
valid locator terminators begin
with 20 Hex (space) and
increase from there. For
instance, if the puck on a
tablet has 4 buttons, the first
button must generate a 20 Hex
as a terminator, the second a
21 Hex, the third a 22 Hex, and
the fourth a 23 Hex.
Final x-coordinate of locator in
NDC/RC units.
Final y-coordinate of locator in
NDC/RC units.
7-4
GEM VDI Programmer's Guide
Input Locator, Request Mode
C BINDING
Procedure Name
Data Types
Input Arguments
Output Functions
vrq_locator( handle, x, y, &xout,
&term )
WORD vrq_locator ( );
WORD handle;
WORD X, y;
WORD xout;
WORD yout;
WORD term;
handle = contrl[6]
x = ptsin[0]
y = ptsinfl]
xout = ptsout[0]
yout = ptsoutfl]
term = intout[0]
&yout,
7-5
GEM VDI Programmer's Guide
Input Locator, Sample Mode
INPUT LOCATOR,
SAMPLE MODE
This function returns the position in NDCs
of the specified locator device. Upon entry to
the locator routine, no cursor is displayed.
(Use Show Cursor to display the cursor.) Input
is sampled. If the cursor position has
changed, GEM VDI returns the cursor position
and contrl(2) is set to 1. Contrl(4) is set to
0. If a terminating event occurred, GEM VDI
returns a character and contrl(4) is set to 1.
Contrl(2) is set to 0.
Note: If both a keyboard and another locator
device are available, the input comes from
either, giving the user maximum flexibility.
Input
contrl(O) — Opcode = 28.
contrl(l) -- Number of input vertices = 1.
contrl(3) — Length of intin array = 0.
contrl(6) — Device handle.
ptsin(O) — Initial x-coordinate of locator
in NDC/RC units.
ptsin(l) — Initial y-coordinate of locator
in NDC/RC units.
Output contrl(2) — Number of output vertices.
1 = coordinate changed
0 = no coordinate changed
contrl(4) — Length of intout array.
0 = no keypress character
1 = keypress character
returned
7-6
GEM VDI Programmer's Guide
Input Locator, Sample Mode
Table 7-1. Sample Mode Status Returned
Event
Control
(2)
Array
(4)
Coordinates change.
1
0
Key pressed; coordinates
not changed from what
was pressed.
0
1
No input.
0
0
Key pressed; coordinates
changed.
1
1
intout(O)
ptsout(O)
ptsout(l)
Locator keypress if keypress
occurs.
This information is the same as
for Input Locator, Request Mode
function.
New x-coordinate of locator in
NDC/RC units.
New y-coordinate of locator in
NDC/RC units.
7-7
GEM VDI Programmer's Guide
Input Locator, Sample Mode
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
status = vsm_locator( handle, x, y, &xout,
&yout, Scterm )
WORD status;
WORD vsm_locator ( );
WORD handle;
WORD x, y ;
WORD xout;
WORD yout;
WORD term;
handle = contrl[6]
x = ptsinCO]
y = ptsinCl]
status = contrl[2] | (contrl[4] << 1)
xout = ptsout[0]
yout = ptsout[l]
term = intout[0]
7-8
GEM VDI Programmer's Guide
Input Valuator, Request Mode
INPUT VALUATOR, This function returns the value of the
REQUEST MODE valuator device. The initial value of the
valuator is incremented or decremented until a
terminating character is struck. Valuator keys
are typically the up-arrow and down-arrow keys.
Valuator numbers range from 1 to 100. Typical
implementation of the up-arrow and down-arrow
keys is as follows:
• Pressing the up-arrow key adds ten to the
valuator.
• Pressing the down-arrow key subtracts ten
from the valuator.
• Pressing the up-arrow key with the Shift key
adds one to the valuator.
• Pressing the down-arrow key with the Shift
key subtracts one from the valuator.
Note: This function is not required and may
not be available on all devices.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 29.
Number of input
Length of intin
Device handle.
vertices = 0.
array = 1.
intin(0)
Initial value.
Output
contrl(2)
contrl(4)
Number of output vertices = 0.
Length of intout array = 2.
intout(0) — Output value,
intout(1) — Terminator.
7-9
GEM VDI Programmer's Guide
Input Valuator, Request Mode
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vrq_valuator( handle, valuator_in,
Svaluator out, sterminator )
WORD vrq_valuator ( );
WORD handle;
WORD valuator_in;
WORD valuator_out;
WORD terminator;
handle = contrl[6]
valuator_in = intin[0]
valuator_out = intout[0]
terminator = intout[1]
7-10
GEM VDI Programmer's Guide
Input Valuator, Sample Mode
INPUT VALUATOR, This function returns the current value of
SAMPLE MODE the valuator device. The valuator device is
sampled. If the valuator has changed, GEM VDI
increments or decrements the valuator value as
required. If a terminating event occurs, GEM
VDI returns the value. If nothing happens, GEM
VDI returns no value. Valuator numbers range
from 1 to 100. The suggested keys are the same
as for Input Valuator, Request Mode.
Note: This function is not required and may
not be available on all devices.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 29.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(O)
Initial value.
Output
contr1(2)
contrl(4)
intout(0)
intout( 1)
Number of output vertices = 0.
Length of intout array.
0 = nothing happened
1 = valuator changed
2 = keypress character
New valuator value.
Keypress, if keypress event
occurred.
7-11
GEM VDI Programmer's Guide
Input Valuator, Sample Mode
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vsm_valuator( handle, val_in, &val_out,
Scterm, &status )
WORD vsm_valuator ( );
WORD handle;
WORD val_in;
WORD val_out;
WORD term;
WORD status;
handle = contrl[6]
val in = intin[0]
val_out = intout[0]
term = intout[l]
status = contrl[4]
7-12
GEM VDI Programmer's Guide
Input Choice, Request Mode
INPUT CHOICE, This function returns the choice status of
REQUEST MODE the selected choice device. Input is sampled
until a key is pressed. If it is a valid
choice key, GEM VDI returns its value.
Otherwise, GEM VDI returns the initial choice
number. Choice numbers range from 1 to a
device-dependent maximum value.
Note: This function is not required and may
not be available on all devices.
Input contrl(O) — Opcode = 30.
contrl(l) — Number of input vertices = 0.
contrl{3) — Length of intin array = 1.
contrl(6) — Device handle.
intin(O) — Initial choice number.
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 1.
intout(O) — Choice number.
C BINDING
Procedure Name vr q choice( handle, ch_in, &ch_out )
Data Types WORD vrq_choice ( );
WORD handle?
WORD ch_in?
WORD *ch out ?
Input Arguments handle = contrl[6]
ch in = intin[0]
Output Arguments *ch_out = intout[0]
7-13
GEM VDI Programmer's Guide
Input Choice, Sample Mode
INPUT CHOICE,
SAMPLE MODE
This function returns the choice status of
the selected choice device. Upon entry to the
routine, GEM VDI samples input. If input is
available and is a valid choice key, GEM VDI
returns it. Choice numbers range from 1 to a
device-dependent maximum value.
Note: This function is not required and may
not be available on all devices.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 30.
Number of input vertices = 0.
Length of intin array = 0.
Device handle.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Choice status.
0 = nothing happened
1 = sample successful
intout(0) —
Choice number if sample
successful, 0 if unsuccessful.
C BINDING
Procedure Name status = vsm__choice( handle, &choice )
Data Types WORD status;
WORD vsm_choice ( );
WORD handle;
WORD choice;
Input Arguments
Output Arguments
handle = contrl[6]
choice = intout[0]
status = contrl[4]
7-14
GEM VDI Programmer's Guide
Input String, Request Mode
This function returns a string from the
specified device. Input is accumulated until
GEM VDI encounters a carriage return or the
intout array is full. If the application
enables echo mode, text will be echoed to the
screen with the current text attributes using
the vertex passed in the ptsin array as the
justification point.
If the number in intin(O) is negative, the
values in intout will conform to the standard
keyboard defined in Appendix D. In this case,
the absolute value of intin(O) is used as the
maximum intout size.
Note: Echoing of input is not required and may
not be available on all devices.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 31.
Number of input vertices = 1.
Length of intin array = 2.
Device handle.
intin(O)
intin(l)
Maximum string length.
Echo mode.
0 = no echo
1 = echo input characters' at
position specified
ptsin(O)
ptsin(l)
x-coordinate of echo area in
NDC/RC units.
y-coordinate of echo area in
NDC/RC units.
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array.
intout — Output string returned in ADE.
INPUT STRING,
REQUEST MODE
7-15
GEM VDI Programmer's Guide
Input String, Request Mode
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vrq_string( handle, max_length, echo__mode,
echo_xy, &string )
WORD vrq_string ( );
WORD handle;
WORD max_length;
WORD echo_mode;
WORD echo_xy[2];
BYTE string[max_length+l];
handle = contrl[6]
max_length = intin[0]
echo_mode = intin[l]
echo_x,y = ptsin[0-l]
string = intout
Note: The BYTE array elements contain the
eight least significant bits of the intout
array elements. The array is terminated with a
null byte. The length of the output variable
string includes an additional byte for the
terminating null.
7-16
GEM VDI Programmer's Guide
Input String, Sample Mode
INPUT STRING,
SAMPLE MODE
This function returns a string from the
specified device. Upon entry to the routine,
GEM VDI samples input. If data is available,
it is accumulated, and GEM VDI samples the
input again. Input is accumulated until one of
the following events occurs:
• Data is no longer available.
• A carriage return is encountered.
• The intout buffer is full.
Note: If the string will always be terminated
with RETURN, use Input String, Request Mode.
If the number in intin(O) is negative, the
values in intout will conform to the standard
keyboard defined in Appendix D. In this case,
the absolute value of intin(O) is used as the
maximum intout size.
Input
contrl(O) — Opcode =31.
contrl(l) — Number of input vertices = 1.
contrl(3) — Length of intin array = 2.
contrl(6) — Device handle.
intin(O) — Maximum string length.
intin(l) — Echo mode.
0 = no echo
1 = echo input characters
ptsin(O) — x-coordinate of echo area in
NDC/RC units.
ptsin(l) — y-coordinate of echo area in
NDC/RC units.
Output
contrl(2)
contrl(4)
intout
Number of output vertices = 0.
Length of output string.
0 = sample unsuccessful
(characters not available)
>0 = sample successful
(characters available)
Output string, if sample
successful.
7-17
GEM VDI Programmer's Guide
Input String, Sample Mode
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
status = vsm_string( handle, max_length,
echo_mode, echo_xy, &string )
WORD vsm_string ( );
WORD handle;
WORD max_length;
WORD echo_mode;
WORD echo_xy[2];
BYTE string[max_length+l];
WORD status;
handle = device handle
max_length = intin[0]
echo_mode = intin[l]
echo_xy - ptsin[0-l]
string = intout
status = contrl[4]
Note: The BYTE array elements contain the
eight least significant bits of the intout
array elements. The array is terminated with a
null byte. The length of the output variable
string includes an additional byte for the
terminating null.
7-18
GEM VDI Programmer's Guide
Set Mouse Form
SET MOUSE This function redefines the cursor pattern
FORM displayed during locator input or at any time
the cursor is shown (see the discussion of the
Show Cursor function later in this section) .
For the cursor mask and data, bit 15 of word 1
is the upper left bit of the pattern. Bit 0 of
word 16 is the lower right bit of the pattern.
Bit zero is the Least Significant Bit of the
word.
The hot spot is the location of the pixel
(relative to the upper left pixel of the mouse
form) that lies over the pixel whose address is
returned by the input locator function.
The mouse form is drawn as follows:
1. The data under the mouse form is saved so
that it can be restored when the cursor
moves.
2. Is in the mask cause the corresponding pixel
to be set to the color index defined in
intin(3).
3. Is in the mouse form data cause the
corresponding pixel to be set to the color
index defined in intin(4).
Input
Contrl(O)
Contrl(l)
Contr1(3)
Contr1(6)
Opcode = 111.
Number of input vertices = 0.
Length of intin array = 37.
Device Handle.
intin(O)
intin(l)
intin(2)
intin(3)
intin(4)
intin(5-20) -
intin(21-36)-
x-coordinate of hot spot,
y-coordinate of hot spot.
Reserved for future use, must be
1 .
Mask color index, normally 0.
Data color index, normally 1.
16 words of 16-bit cursor mask.
16 words of 16-bit cursor data.
Output Contr 1(2) — Number of output vertices = 0.
Contr 1(4) — Length of intout array = 0.
7-19
GEM VDI Programmer's Guide Set Mouse Form
C BINDING
Procedure Name vsc_form( handle, pcur_form )
Data Types WORD vsc_form ( );
WORD handle?
WORD pcur_form[37];
Input Arguments handle = contrl[6]
pcur_form[0] = intin[0]
pcur_form[36] = intin[36]
7-20
GEM VDI Programmer's Guide
Exchange Timer Interrupt Vector
EXCHANGE TIMER With this function, the application can
INTERRUPT VECTOR perform some action each time a timer tick
occurs.
The input to this function is a two-word
pointer in contrl(7) and contrl(8). The
pointer indicates the starting address of the
code to receive control when a timer tick
occurs. The address of the old timer routine
is returned in contrl(9) and contrl(lO).
The application-dependent code is invoked with
a processor-dependent call instruction. When
this is complete, the application should
perform a processor-dependent return
instruction.
It is the responsibility of the application-
dependent code to save and restore any
registers used.
When the application code is invoked,
interrupts are disabled. The application
should not enable interrupts.
See Appendix E for processor specific
instructions and register names.
The number of milliseconds per timer tick is
returned in intout(O).
Input
contrl(O) —
contrl(l) —
contrl(3)
contrl(6)
contrl(7-8) —
Opcode = 118.
Number of input vertices = 0.
Length of intin array = 0.
Device handle.
Address of application timer
routine.
Output
contrl(2)
contrl(4)
contrl(9-10 )-
Number of output vertices = 0.
Length of intout array = 1.
Address of the old timer
routine.
intout(O) —
Milliseconds per tick.
7-21
GEM VDI Programmer's Guide
Exchange Timer Interrupt Vector
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vex_timv( handle,
&tim conv )
tim addr, ot
WORD vex_timv( );
WORD handle;
WORD *tim__addr;
WORD *otim_addr;
WORD tim conv;
handle = contrl[6]
tim addr = contrl[7-8]
otim_addr = contrl[9-10]
tim conv = intout[0]
im_addr.
7-22
GEM VDI Programmer's Guide
Show Cursor
SHOW CURSOR This function displays the current cursor. The
cursor moves on the display surface based on
information input from a mouse.
The Show Cursor function and the Hide Cursor
functions are closely related. Once the cursor
is visible, a single Hide Cursor causes the
cursor to disappear. GEM VDI keeps track of
the number of times the Hide Cursor function is
called. The Show Cursor function must be
called the same number of times for the cursor
to reappear. For example, if the Hide Cursor
function is called four times, the Show Cursor
function must be called four times for the
cursor to appear.
The Show Cursor function does, however, provide
a reset flag in intin(O). If intin(O) is zero,
the cursor appears on the screen, regardless of
the number of Hide Cursor calls. A nonzero
value for intin(O) affects the Show Cursor
function as described in the preceding
paragraph.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 122.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(O)
Reset flag.
0 = ignore number of Hide
Cursor calls
nonzero = normal Show Cursor
functionality
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 0.
7-23
GEM VDI Programmer's Guide
Show Cursor
C BINDING
Procedure Name
Data Types
v_show__c( handle, reset )
WORD v_show_c ( );
WORD handle;
WORD reset
Input Arguments
handle = contrl[6]
reset = intinCO]
GEM VDI Programmer's Guide
Hide Cursor
HIDE CURSOR This function removes the cursor from the
display surface. This state is the default
condition set at Open Workstation. The cursor
can appear in a new position when the
application calls the Show Cursor function
because GEM VDI updates the position based on
information input from a mouse.
Refer to the Show Cursor function for a
description of how the number of Hide Cursor
calls affects the Show Cursor function.
Input
contr1(0)
contrl(l)
contr1(3)
contr1(6)
Opcode = 123.
Number of input vertices = 0.
Length of intin array = 0.
Device handle.
Output contr1(2) — Number of output vertices = 0.
contr1(4) — Length of intout array = 0.
C BINDING
Procedure Name v_hide_c( handle )
Data Types WORD v_hide_c ( )?
WORD handle;
Input Arguments handle = contr1[6]
7-25
GEM VDI Programmer's Guide
Sample Mouse Button State
SAMPLE MOUSE
BUTTON STATE
This function returns the current state of
the mouse buttons. The leftmost mouse button is
returned in the Least Significant Bit of the
word. A bit value of 1 indicates the key is
currently depressed; a bit value of 0 indicates
the key is up.
This function also returns the current (x,y)
position of the cursor.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 124.
Number of input vertices = 0.
Length of intin array = 0.
Device handle.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 1.
Length of intout array = 1.
intout(O) —
Mouse button state.
ptsout(O) —
ptsout(l) —
x position of cursor in NDC/RC
units.
y position of cursor in NDC/RC
units.
C BINDING
Procedure Name vq_mouse( handle, &pstatus, &x, &y )
Data Types WORD vq_mouse { );
WORD handle;
WORD pstatus;
WORD x, y;
Input Arguments handle = contrl[6]
Output Arguments pstatus = intout[0]
x = ptsout[0]
y = ptsoutCl]
7-26
GEM VDI Programmer's Guide
Exchange Button Change Vector
EXCHANGE BUTTON This function allows the application to
CHANGE VECTOR perform some action each time the state of the
mouse buttons changes. The application
receives control after the button state is
decoded, but before the driver button state
changes.
The input to this function is a two-word
pointer in contrl(7) and contrl(8), which
indicates the starting address of the code to
receive control when the mouse button state
changes. Contrl(9) and contrl(lO) return a
two-word pointer to the old mouse routine.
Control is passed to the specified address
whenever the mouse button state changes. The
application code is invoked via a processor-
dependent call instruction with a processor-
dependent register containing the mouse button
keys. Keys are encoded by the same rules that
apply to the Sample Mouse Button State
function. When complete, the application-
dependent code should do a processor-dependent
return instruction with the mouse button state
the driver is to store in the same register.
This gives the application the opportunity to
alter the buttons before they are used by the
driver.
It is the responsibility of the application-
dependent code to save and restore any
registers used.
When the application code is invoked,
interrupts are disabled. The application
should not enable interrupts.
See Appendix E for processor-specific
instructions and register names.
Input
Contrl(O) —
Opcode = 125.
Contrl(l) —
Number of input vertices = 0.
Contrl(3) —
Length of intin array = 0.
Contrl(6) —
Device handle.
Contr1(7-8) —
Address of application mouse
button state change routine.
7-27
GEM VDI Programmer's Guide
Exchange Button Change Vector
Output
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
Contrl(2) — Number of output vertices = 0.
Contrl(4) — Length of intout array = 0.
Contrl(9-10) - Address of old mouse button
state change routine.
vex_butv( handle, pusrcode, psavcode )
WORD vex_butv ( ) ;
WORD handle;
WORD *pusrcode;
WORD *psavcode;
handle = contrl[6]
pusrcode = contrl[7-8]
psavcode = contrl[9-10]
7-28
GEM VDI Programmer's Guide
Exchange Mouse Movement Vector
EXCHANGE MOUSE This function allows the application to
MOVEMENT VECTOR perform some action each time the mouse moves to
a new location. The application receives
control after the x,y address is computed, but
before the current mouse position in the driver
is updated or the mouse form is actually
redrawn on the screen.
The input to this function is a two-word
pointer in contrl(7) and contrl(8), which
indicates the starting address of the code to
receive control when the mouse moves. A two-
word pointer to the address of the old mouse
movement routine is returned in contrl(9) and
contr1(10).
When the mouse moves, the application-dependent
code is invoked via a processor-dependent call
instruction. The new x and y locations are
contained in a pair of processor-dependent
registers. Upon completion, the application-
dependent code should do a processor-dependent
return instruction with the x,y mouse position
the driver is to store in the appropriate
hardware registers. This procedure gives the
opportunity to alter the x,y position before it
is used by the driver.
It is the responsibility of the application-
dependent code to save and restore any
registers used.
When the application code is invoked,
interrupts are disabled. The application
should not enable interrupts.
See Appendix E for processor-specific
instructions and register names.
7-29
GEM VDI Programmer's Guide
Exchange Mouse Movement Vector
Input
Contrl(O) — Opcode = 126.
Contrl(l) — Number of input vertices = 0.
Contrl(3) — Length of intin array = 0.
Contrl(6) — Device handle.
Contrl(7-8) — Address of application mouse
movement routine.
Output
Contrl(2) — Number of output vertices = 0.
Contrl(4) — Length of intout array = 0.
Contrl(9-10) - Address of the old mouse
movement routine.
C BINDING
Procedure Name
vex motv( handle, pusrcode, psavcode )
Data Types
WORD vex__motv ( ) ?
WORD handle;
WORD *pusrcode;
WORD *psavcode;
Input Arguments
handle = contrl[6]
pusrcode = contrl[7-8]
Output Arguments
psavcode = contrl[9-10]
7-30
GEM VDI Programmer's Guide
Exchange Cursor Change Vector
EXCHANGE CURSOR
CHANGE VECTOR
This function allows the application to
perform some action each time the cursor is
drawn. The application can completely take
over drawing the cursor or can perform some
action and have GEM VDI draw the cursor.
Control is passed to the application whenever
the cursor position should be updated.
The input to this function is a two-word
pointer in contrl(7) and contrl(8), which
indicates the starting address of the code to
receive control when a cursor is drawn. The
address of the old cursor draw routine is
returned in contrl(9) and contrl(lO).
The application-dependent code is invoked with
a processor-dependent call instruction. The
x,y position at which the cursor should be
drawn is contained in a pair of processor-
dependent registers. If the application-
dependent code does not draw its own cursor, a
processor-dependent call should be performed to
the address returned in contrl(9) and
contrl(lO). This will cause GEM VDI to draw a
cursor. When it is done, the application
should perform a processor-dependent return
instruction.
It is the responsibility of the application-
dependent code to save and restore any
registers used. The GEM VDI cursor draw
routine preserves the contents of all
registers.
When the application code is invoked,
interrupts are disabled. The application
should not enable interrupts.
See Appendix E for processor-specific
instructions and register names.
7-31
GEM VDI Programmer's Guide
Exchange Cursor Change Vector
Input
contrl{0) —
contrl(l) —
contrl(3) —
contrl(6) —
contrl(7-8) —
Opcode = 127.
Number of input vertices = 0.
Length of intin array = 0.
Device handle.
Address of application cursor
draw routine.
Output
contrl(2) —
contrl(4) —
contrl(9-10) -
Number of output vertices = 0.
Length of intout array = 0.
Address of the old cursor draw
routine.
C BINDING
Procedure Name
vex_curv( handle, pusrcode, psavcode
Data Types
WORD vex_curv ( );
WORD handle;
WORD *pusrcode;
WORD *psavcode;
Input Arguments handle = contrl[6]
pusrcode = contrl[7-8]
Output Arguments psavcode = contrl[9-10]
7-32
GEM VDI Programmer's Guide
Sample Keyboard State Information
SAMPLE KEYBOARD
STATE INFORMATION
This function returns the current state of
the keyboard's Control, Shift, and Alt keys.
These values are returned as a bit-encoded
value in intout(O). The keys are assigned to
bits as follows:
Bit 0 - right Shift Key
Bit 1 - left Shift Key
Bit 2 - Control Key
Bit 3 - Alt Key
Bit 0 is the Least Significant Bit of the word.
A bit value of zero indicates the key is up, a
bit value of 1 indicates the key is depressed.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 128.
Number of input vertices = 0.
Length of intin array = 0.
Device handle.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 1.
intout(O) —
Keyboard state.
C BINDING
Procedure Name
Data Types
Input Arguments
vq_key_s( handle, &pstatus )
WORD vq_key_s ( );
WORD handle;
WORD pstatus;
handle = contrl[6]
Output Arguments pstatus = intout[0]
End of Section 7
7-33
Section 8
Inquire Functions
INTRODUCTION Inquire functions return the current settings
for device-specific attributes.
EXTENDED INQUIRE This function returns additional device¬
specific information not included in the Open
Workstation call. The value of intin(O)
determines if GEM VDI returns the values
returned at Open Workstation or an extended set
of device-specific information. Refer to
Section 3, "Control Functions," for more
information about intout values for the Open
Workstation function.
Note that 6 vertices and 45 intouts are always
returned, although some values are undefined
for the extended device information.
Input
contrl(0)
contrl(1)
contrl(3)
contrl(6)
Opcode = 102.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(O) — Information type.
0 = Open Workstation values
1 = Extended Inquire values
8-1
GEM VDI Programmer's Guide
Extended Inquire
Output contrl(2) —
contrl(4) —
intout(O) —
intout(l) —
intout(2) —
intout(3) —
intout(4) —
intout(5) —
intout(6) —
intout(7) —
intout(8) —
Number of output vertices = 6.
Length of intout array = 45.
Type of screen.
0 — not screen
1 — separate alpha and graphic
controllers and separate
video screens
2 — separate alpha and graphic
controllers with a common
video screen
3 — common alpha and graphic
controller with separate
image memory
4 — common alpha and graphic
controller with common
image memory
Number of background colors
available in color palette.
On some devices this may be
different from the number of
colors returned from Open
Workstation, intout(39).
Text effects supported.
(See "Set Graphic Text Special
Effects" in Section 5 for
values.)
Scale rasters.
0 = scaling not possible
1 = scaling possible
Number of planes.
Lookup table supported.
0 = table supported
1 = table not supported
Performance factor, number of 16
x 16 pixel raster ops per
second.
Contour fill capability.
Character rotation ability.
0 = none
1 = 90-degree increments only
2 = arbitrary angles
8-2
GEM VDI Programmer's Guide
Extended Inquire
intout(9) —
intout(lO)—
intout(ll) —
intout(12) —
intout(13) —
intout(14)—
intout(l5)—
intout(16)—
intout(17)—
intout(18)—
intout(19-44)
ptsout(0-11)
Number of writing modes
available.
Highest level of input mode
available.
0 = none
1 = request
2 = sample
Text alignment capability flag.
0 = no
1 = yes
Inking capability flag.
0 = device cannot ink
1 = device can ink
Rubberbanding capability flag.
0 = no
1 = capable of rubberband lines
2 = capable of both rubberband
lines and rectangles
Maximum vertices for Polyline,
Polymarker, or Filled Area.
-1 = no maximum
Maximum intin.
-1 = no maximum
Number of keys available on the
mou se.
Styles for wide lines.
0 = no
1 = yes
Writing modes for wide lines.
Reserved, contains zeros.
Reserved, contains zeros.
8-3
GEM VDI Programmer's Guide
Extended Inquire
C BINDING
Procedure Name vq_extnd( handle, owflag, work_out )
Data Types WORD vq_extnd ( );
WORD handle;
WORD owflag;
WORD work out[57]
Input Arguments handle = contrl[6]
owflag = intin[0]
Output Arguments work_out[0] = intout[0]
work_out[44] = intout[44]
work_out[45] = ptsoutCO]
work_out[56] = ptsout[ll]
8-4
GEM VDI Programmer's Guide
Inquire Color Representation
INQUIRE COLOR
REPRESENTATION
This function returns either the requested or
the actual value of the specified color index in
RGB units. Both the set and realized values
are available. If the selected index is out of
range, GEM VDI returns -1 in intout(O).
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 26.
Number of input vertices = 0.
Length of intin array = 2.
Device handle.
intin(O)
intin(l)
Requested color index.
Set or realized flag.
0 = set ( return color values
requested)
1 = realized (return color
values realized on device)
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 4.
intout(O) —
intout(1) —
intout(2) —
intout(3) —
Color index.
Red intensity (in tenths of
percent 0-1000).
Green intensity.
Blue intensity.
8-5
GEM VDI Programmer's Guide
Inquire Color Representation
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vq_color( handle, color_index, set_flag, rgb )
WORD vq_color ( );
WORD handle?
WORD color_index?
WORD set_flag;
WORD rgb[3];
handle = contrl[6]
color__index = intin[0]
set_flag = intin[l]
rgb[0] = intout[l]
rgb[l] = intout[2]
rgb[2] = intout[3]
8-6
GEM VDI Programmer's Guide
Inquire Polyline Attributes
INQUIRE CURRENT
POLYLINE
ATTRIBUTES
This function reports the current setting of
all attributes that affect polylines, such as
line type, line color, line width, end styles,
and writing mode.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode
Number
Length
Device
= 35.
of input vertices = 0.
of intin array = 0.
handle.
Output contrl(2) —
contrl(4) —
intout(O) —
intout(1) —
intout(2) —
intout(3) —
intout(4) —
ptsout(O) —
ptsout(l) —
Number of output vertices = 1.
Length of intout array = 5.
Current polyline line type.
(Refer to Set Polyline Line
Type function.)
Current polyline line color
index.
Current writing mode.
(Refer to the Set Writing Mode
function. )
End style for beginning point of
polyline.
End style for ending point of
polyline.
Current line width, in current
coordinate system.
0 .
8-7
GEM VDI Programmer's Guide
Inquire Polyline Attributes
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vql_attributes( handle.
WORD vql_attributes ( )
WORD handle?
WORD attrib[4];
handle = contrl[6]
attribCO] = intoutCO]
attrib[l] = intout[l]
attrib[2] = intout[2]
attrib[3] = ptsout[0]
attrib )
8-8
GEM VDI Programmer's Guide
Inquire Polymarker Attributes
INQUIRE CURRENT This function reports the current setting of
POLYMARKER all attributes that affect polymarkers, such
ATTRIBUTES as marker type, marker color, marker height, and
writing mode.
Input contrl(O) — Opcode = 36.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 0.
contrl(6) — Device handle.
Output contrl(2) — Number of output vertices = 1.
contrl(4) — Length of intout array = 3.
intout(O) — Current polymarker marker type.
(Refer to Set Polymarker Type
function.)
intout(1) — Current polymarker marker color
index.
intout(2) — Current writing mode.
(Refer to the Set Writing Mode
function for description.)
ptsout(O) — Current polymarker width, in
current coordinate system.
ptsout(l) -- Current polymarker height, in
current coordinate system.
8-9
GEM VDI Programmer's Guide
Inquire Polymarker Attributes
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vqm_attributes( handle.
WORD vqm_attributes ( )
WORD handle;
WORD attrib[4];
handle = contrl[6]
attrib[0] = intoutCO]
attrib[l] = intoutCl]
attrib[2] = intout[2]
attrib[3] = ptsoutCl]
attrib )
8-10
GEM VDI Programmer's Guide
Inquire Fill Area Attributes
INQUIRE CURRENT
FILL AREA
ATTRIBUTES
This function reports the current setting of
all attributes that affect fill areas, such
as interior style, fill color, fill style index,
and writing mode.
Input
contrl(O) — Opcode = 37.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 0.
contrl(6) — Device handle.
Output contr1(4)
contrl(6)
intout(0)
intout(1)
intout(2)
intout(3)
intout(4)
Number of output vertices = 0.
Length of intout array = 5.
Current fill area interior style.
(Refer to Set Fill Interior Style
function.)
Current fill area color index.
Current fill area style index.
(Refer to Set Fill Style Index
function.)
Current writing mode.
(Refer to the Set Writing Mode
function. )
Current fill perimeter status.
8-11
GEM VDI Programmer's Guide
Inquire Fill Area Attributes
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vqf_attributes( handle, attrib )
WORD vqf_attributes( );
WORD handle?
WORD attrib[4];
handle = contrl[6]
attribCO]
attrib[l]
attrib[2]
attrib[3]
intout[0]
intout[1]
intout[2]
intoutE 3]
8-12
GEM VDI Programmer's Guide
Inquire Graphic Text Attributes
INQUIRE CURRENT
GRAPHIC TEXT
ATTRIBUTES
This function returns the current setting of
all attributes that affect graphic text, such
as text size, text color, text face alignment,
baseline rotation, and writing mode.
Input
contrl(0)
contrl(l)
contrl(3)
contrl(6)
Opcode = 38.
Number of input vertices = 0.
Length of intin array = 0.
Device handle.
Output contr1(2)
contrl(4)
intout( 0)
intout(1)
intout(2)
intout(3)
intout(4)
intout(5)
ptsout(0)
ptsout (1)
ptsout(2)
ptsout(3)
Number of output vertices = 2.
Length of intout = 6.
Current graphic text face.
Current graphic text color
index.
Current angle of rotation of
text baseline ( in tenths of
degrees 0-3600).
Current horizontal alignment.
(Refer to Set Graphic Text
Alignment function.)
Current vertical alignment.
(Refer to Set Graphic Text
Alignment function.)
Current writing mode.
(Refer to the Set Writing Mode
function.)
Current character width in
current coordinate system.
Current character height in
current coordinate system.
Current character cell width in
current coordinate system.
Current character cell height in
current coordinate system.
8-13
GEM VDI Programmer's Guide
Inquire Graphic Text Attributes
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vqt_attributes( handle, attrib )
WORD vqt_attributes ( );
WORD handle;
WORD attrib[10];
handle = contrl[6]
attrib[0] = intout[0]
attrib[l] = intout[l]
attrib[5] = intout[5]
attrib[6] = ptsout[0]
attrib[9]
ptsout[3]
8-14
GEM VDI Programmer's Guide
Inquire Text Extent
INQUIRE
EXTENT
Input
TEXT This function returns a rectangle that
encloses the requested string. The coordinates
of the vertices are given relative to a
coordinate system defined such that the extent
rectangle touches both the x and y axes, and
the string is in the first quadrant. All text
attributes, including style and baseline
rotation, affect the calculation.
Figure 8—1. Inquire Text Extent Function
contrl(0)
contrl(l)
contr1(3)
contrl(6)
Opcode = 116.
Number of input vertices = 0.
Number of words in text.
Device handle.
intin
Character string in current
character set.
8-15
GEM VDI Programmer's Guide
Inquire Text Extent
Output
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
contrl(2) — Number of output vertices = 4.
contrl(4) — Length of intout array = 0.
ptsout(O) —
ptsout(l) —
ptsout(2) —
ptsout(3) —
ptsout(4) —
ptsout(5) —
ptsout(6) —
ptsout(7) —
delta-x
for
point
1 of the
s t r i n g
i n
the
current
coordinate system.
delta-y
for
point
1 of the
s t r i n g
i n
the
current
coordinate system.
delta-x
for
point
2 of the
s t r i n g
i n
the
current
coordinate system.
delta-y
for
point
2 of the
s t r i n g
i n
the
current
coordinate system.
delta-x
for
point
3 of the
s t r i n g
i n
the
current
coordinate system.
delta-y
for
point
3 of the
string
i n
the
current
coordinate system.
delta-x
for
point
4 of the
s t r i n g
i n
the
current
coordinate system.
delta-y
for
point
4 of the
s t r i n g
i n
the
current
coordinate system.
vqt_extent( handle, string, extent )
WORD vqt_extent( );
WORD handle;
WORD extent[8D;
BYTE stringC];
handle = contrl[6]
string = intin
extent[0] = ptsout[0]
extent[7] = ptsout[7]
8-16
GEM VDI Programmer's Guide
Inquire Character Cell Width
INQUIRE CHARACTER
CELL WIDTH
Input
This function returns the character cell
width for a specified character in the current
text face. The character cell width is the
distance from the left edge of the character to
the left edge of the character that follows it
in a text string. Special effects and rotation
do not apply. GEM VDI returns all values in
the current coordinate system.
Lett Character
Alignment
Delta
Right Character
Alignment
Delta
' * ‘
' * '
_
1
m
1
1
■
Character
Width
Cell
Height
Cell
Width
Figure 8-2. Character Cell Definition
contrl(0)
contr1(1)
contr1(3)
contr1(6)
Opcode = 117.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(0)
Character value in current
character set in ADE format.
8-17
GEM VDI Programmer's Guide
Inquire Character Cell Width
Output
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
contrl(2) — Number of output vertices = 3.
contrl(4) — Length of intout array = 1.
intout(O) —
ptsout(O) —
ptsout(l) —
ptsout(2) —
ptsout(3) —
ptsout(4) —
ptsout(5) —
ADE value of the character being
inquired on; -1 if an invalid
character (status).
Cell width of the character in
the current coordinate system.
0 .
Left character alignment delta.
0 .
Right character alignment delta.
0 .
status = vqt_width( handle, character,
&cell_width, &left_delta, &right_delta )
WORD status;
WORD vqt_width( );
WORD handle;
BYTE character;
WORD cell_width;
WORD left_delta;
WORD right_delta;
handle = contrl[6]
character = intin[0]
status = intout[0]
cell_width = ptsout[0]
left_delta = ptsout[2]
right_delta = ptsout[4]
8-18
GEM VDI programmer's Guide
Inquire Face Name and Index
INQUIRE FACE NAME This function returns a 32-character string
AND INDEX that describes the face. The face is selected
by its element number (1 to the number of faces
available). One word of zero in the intin
array terminates the string.
The string describing the face is returned in
ADE form in intout( 1. . . 32 ). The face ID to
access this face with Set Text Face is returned
in intout(l). The first 16 characters name the
face. The next 16 characters describe the
style and weight. See Table 8-1 for a sample
of the possible configurations.
Table 8-1. Face Nanes and Styles
Face Name
Styles
Swiss
721
Light
Swiss
721
Thin Italic
Dutch
801
Roman
Du tch
801
Bold Italic
Input
contrl(0)
contrl(l)
contrl(3)
contrl(6)
Opcode = 130.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(0)
Element number.
Output
contrl(2) —
Number of
output
vertices = 0
contrl(4) —
Length of
intout
array = 33.
intout(O) —
ID number.
intout(1) to
intout(32) -
32 ADE.
8-19
GEM VDI programmer’s Guide
Inquire Face Name and Index
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
index = vqt_name( handle, element_num, name )
WORD index;
WORD vqt_name( );
WORD handle;
WORD element num,
BYTE name[32T;
handle = contr[6]
element num = intin[0]
index = intoutCO]
name[0] = intout[l]
nameC 31]
intout[32]
Note: The BYTE array elements contain the
eight least significant bits of the intout
array elements. The array is terminated with a
null byte.
8-20
GEM VDI Programmer's Guide
Inquire Current Face Information
INQUIRE CURRENT This function returns size information for
FACE INFORMATION the current face with the current size and
special effects. Because the special effects
may change the cell width and extent, a value
is returned to allow the use of the width
information returned in Inquire Character Cell
Width. When the character is skewed, the cell
contains left and right offsets as shown in
Figure 8-3.
Right Offset
Figure 8-3. Right and Left Offset
Input
contr1(0)
contrl(1)
contrl(3)
contrl(6)
Opcode = 131.
Number of input vertices = 0.
Length of intin array = 0.
Device handle.
Output contrl(2) —
contrl(4) —
intout(O) —
intout(l) —
ptsout(O) —
ptsout(l) —
ptsout(2) —
Number of output vertices = 5.
Length of output array = 2.
Minimum ADE (ASCII Decimal
Equivalent) the first character
in this face.
Maximum ADE, the last character
in this face.
Maximum cell width not including
special effects.
Bottom line distance relative to
baseline.
Special effects delta x. The
current special effects
increase character width by
this amount.
GEM VDI Programmer's Guide
Inquire Current Face Information
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
ptsout(4) —
Left offset; (see Figure 8
-2)
positive value relative
position.
to
ptsout(5) —
Half distance relative
baseline.
to
ptsout(6) —
Right offset (see Figure 8-
2).
ptsout(7) —
Ascent distance relative
baseline.
to
ptsout(8) —
0 .
ptsout(9) —
Top distance relative
baseline.
to
vqt_fontinfo(
distances.
handle, &minADE, SmaxADE,
&maxwidth, effects )
WORD vqt_fontinfo( );
WORD handle;
WORD minADE;
WORD maxADE;
WORD distances[5] ;
WORD maxwidth?
WORD effects[3]?
handle = contrl[6]
minADE = intout[0]
maxADE = intout[l]
distances[0] = ptsout[l]
distances[l] = ptsout[3]
distances[2] = ptsout[5]
distances[3] = ptsout[7]
distances[4] = ptsout[9]
maxwidth = ptsout[0]
effects[0] = ptsout[2]
effects[l] = ptsout[4]
effectsC2] = ptsout[6]
8-22
GEM VDI Programmer's Guide
Inquire Cell Array
INQUIRE CELL ARRAY This function returns the cell array definition
of the specified pixels. Color indices are
returned one row at a time, starting from the
top of the rectangular area, proceeding
downwa rd.
Note: This function is not required and may
not be available on all devices.
Input contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
contrl(7) —
contrl(8) —
ptsin(O)
ptsin(l) —
ptsin(2)
ptsin(3)
Opcode = 27.
Number of input vertices = 2.
Length of intin array = 0.
Device handle.
Length of each row in color
index array.
Number of rows in color index
array.
x-coordinate of lower left
corner in current coordinate
system.
y-coordinate of lower left
corner in current coordinate
system.
x-coordinate of upper right
corner in current coordinate
system.
y-coordinate of upper right
corner in current coordinate
system.
Output contrl(2)
contrl(4)
contrl(9)
contrl(lO) —
contrl(ll) —
Number of output vertices = 0.
Length of the color index array,
same as contrl(3).
Number of elements used in each
row of color index array.
Number of rows used in color
index array.
Invalid value flag.
0 — if no errors
1 — if a color value could
not be determined for
some pixel
8-23
GEM VDI Programmer's Guide
Inquire Cell Array
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
intout — Color index array, stored one
row at time.
-1 — indicates that a color
index could not be
determined for that
particular pixel
vq__cellarray( handle, pxyarray, row_length,
num_rows, &el_used, &rows_used, &status,
colarray )
WORD vq_cellarray( );
WORD handle?
WORD pxyarray[4];
WORD row_length;
WORD num_rows?
WORD el_used;
WORD rows_used;
WORD status;
WORD colarrayCn];
handle = contrl[6]
pxyarray[0] = ptsin[0]
pxyarrayCl] = ptsin[l]
pxyarrayC2] = ptsin[2]
pxyarray[3] = ptsin[3]
row_length = contrl[73
num_rows = contrl[8]
el_used = contrl[9]
rows_used = contrl[10]
status = contrl[ll]
colarrayCO] = intout[0]
colarrayCn] = intin[n]
8-24
GEM VDI Programmer's Guide
Inquire Input Mode
INQUIRE INPUT MODE
This function returns the current input mode for
the specified logical input device: locator,
valuator, choice, and string.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(6) —
Opcode = 115.
Number of input vertices = 0.
Length of intin array = 1.
Device handle.
intin(O)
Logical input device.
1 = locator
2 = valuator
3 = choice
4 = string
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 1.
intout(0) —
Input mode.
1 = request
2 = sample
C BINDING
Procedure Name vqin_mode( handle, dev_type, &input_mode )
Data Types WORD vqin_mode( );
WORD handle;
WORD dev_type;
WORD input_mode;
Input Arguments handle = contrl[6]
dev_type = intin[0]
Output Arguments inputmode = intout[0]
End of Section 8
8-25
Section 9
Escapes
ESCAPE
Input
The Escape function allows the application
program to access the special capabilities of a
graphics device. GEM VDI predefines some
escape functions; others can be defined for
specific devices. The parameters passed depend
on the escape function the application
requests.
contrl(0)
contrl(l)
contrl( 3)
contrl{5)
contr1{6)
Opcode = 5.
Number of input vertices.
Number of input parameters.
Function identifier (id).
Device handle.
Table 9-1. Escape Function Identifiers
Number
Description
1
INQUIRE ADDRESSABLE ALPHA
CHARACTER CELLS
2
EXIT ALPHA MODE
3
ENTER ALPHA MODE
4
ALPHA CURSOR UP
5
ALPHA CURSOR DOWN
6
ALPHA CURSOR RIGHT
7
ALPHA CURSOR LEFT
8
HOME ALPHA CURSOR
9
ERASE TO END OF ALPHA SCREEN
10
ERASE TO END OF ALPHA TEXT LINE
11
DIRECT ALPHA CURSOR ADDRESS
12
OUTPUT CURSOR ADDRESSABLE ALPHA
TEXT
13
REVERSE VIDEO ON
9-1
GEM VDI Programmer's Guide
Escapes
Table 9-1. (continued)
Number
Description
14
REVERSE VIDEO OFF
15
INQUIRE CURRENT ALPHA CURSOR
ADDRESS
16
INQUIRE TABLET STATUS
17
HARD COPY
18
PLACE GRAPHIC CURSOR AT LOCATION
19
REMOVE LAST GRAPHIC CURSOR
20
FORM ADVANCE
21
OUTPUT WINDOW
22
CLEAR DISPLAY LIST
23
OUTPUT BIT IMAGE FILE
24-59
UNUSED BUT RESERVED FOR FUTURE
EXPANSION
60
SELECT PALETTE
61-90
UNUSED BUT RESERVED FOR FUTURE
EXPANSION
91
INQUIRE PALETTE FILM TYPES
92
INQUIRE PALETTE DRIVER STATE
93
SET PALETTE DRIVER STATE
94
SAVE PALETTE DRIVER STATE
95
SUPPRESS PALETTE MESSAGES
96
PALETTE ERROR INQUIRE
98
UPDATE METAFILE EXTENTS
99
WRITE METAFILE ITEM
100
CHANGE GEM VDI FILENAME
>100
UNUSED AND AVAILABLE FOR USE
9-2
GEM VDI Programmer's Guide Escapes
intin — Function-dependent information
described on following pages.
ptsin — Array of input coordinates for
escape function.
Output contrl(2) — Number of output vertices.
contrl(4) — Number of output parameters.
intout — Array of output parameters.
ptsout — Array of output coordinates.
9-3
GEM VDI Programmer's Guide
Inquire Addressable Character Cells
ESCAPE Is INQUIRE
ADDRESSABLE ALPHA
CHARACTER CELLS
This escape returns information to the
calling program about the number of vertical
(row) and horizontal (column) positions at which
the alpha cursor can be positioned on the
screen. Typically, only screens support alpha
text.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 1.
Device handle.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 2.
intout(O) —
intout(1) —
Number of addressable rows on
the screen, (-1 indicates
cursor addressing not
possible).
Number of addressable columns on
the screen, (-1 indicates
cursor addressing not
possible).
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vq_chcells( handle, &rows, Scolumns )
WORD vq_chcells ( );
WORD handle;
WORD rows;
WORD columns;
handle = contrl[6]
rows = intout[0]
columns = intout[l]
9-4
GEM VDI Programmer’s Guide
Exit Alpha Mode
ESCAPE 2 s EXIT This escape causes the graphics device to
ALPHA MODE enter graphics mode if graphics mode is
different from alpha mode. It is used to exit
alpha cursor addressing mode explicitly and to
make the transition from alpha to graphics mode
properly.
Input
contrl(0)
contrl(l)
contrl(3)
contrl(5)
contrl(6)
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 2.
Device handle.
Output
contrl{2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name
v exit cur( handle )
Data Types
WORD v_exit_cur ( )
WORD handle;
Input Arguments
handle = contrl[6]
9-5
GEM VDI Programmer's Guide
Enter Alpha Mode
ESCAPE 3: ENTER
ALPHA MODE
This escape causes the graphics device to
exit graphics mode if graphics mode is different
from alpha mode. It is used to enter the alpha
cursor addressing mode explicitly and to make
the transition from graphics to alpha mode
properly. This opcode also returns the cursor
to the upper left character cell of the display
device.
Input
contrl(0)
contrl(1)
contrl( 3)
contrl(5)
contr1( 6)
Opcode = 5.
Number of input vertices = 0.
— Length of intin array = 0.
Function id = 3.
— Device handle.
Output
contrl (2)
contrl(4)
Number of output vertices = 0.
Length of intout array = 0.
C BINDING
Procedure Name
v enter cur( handle )
Data Types
WORD v_enter_cur ( )
WORD handle;
Input Arguments handle = contrl[6]
9-6
GEM VDI Programmer's Guide
Alpha Cursor Up
ESCAPE 4: ALPHA
CURSOR UP
This escape moves the alpha cursor up one row
without altering its horizontal position. If
the cursor is already at the top margin,
nothing happens.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 4.
Device handle.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 0.
C BINDING
Procedure Name
v_curup( handle )
Data Types
WORD v curup
WORD handle;
( );
Input Arguments handle = contrl[6]
9-7
GEM VDI Programmer's Guide
Alpha Cu r sor Down
ESCAPE 5: ALPHA
CURSOR DOWN
This escape moves the alpha cursor down one
row without altering its horizontal position.
If the cursor is already at the bottom margin,
nothing happens.
Input
contrl(O) — Opcode = 5.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 0.
contrl(5) — Function id = 5.
contrl(6) — Device handle.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name
v_curdown( handle )
Data Types
WORD v curdown ( );
WORD handle;
Input Arguments
handle = contrl[6]
GEM VDI Programmer 1 s Guide
Alpha Cursor Right
ESCAPE 6: ALPHA
CURSOR RIGHT
The Alpha Cursor Right escape moves the alpha
cursor right one column without altering its
vertical position. If the cursor is already at
the right margin, nothing happens.
Input
contrl(0)
contrl(l)
contrl(3)
contrl(5)
contrl(6)
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 6.
Device handle.
Output
contrl( 2)
contr1(4)
Number of output vertices = 0.
Length of intout array = 0.
C BINDING
Procedure Name v_curright( handle )
Data Types WORD v_curright ( );
WORD handle?
Input Arguments
handle = contrl[6]
GEM VDI Programmer's Guide
Alpha Cursor Left
ESCAPE 7: ALPHA
CURSOR LEFT
The Alpha Cursor Left escape moves the alpha
cursor left one column without altering its
vertical position. If the cursor is already at
the left margin, nothing happens.
Input
contrl( 0)
contrl(l)
contrl(3)
contrl(5)
contrl(6)
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 7.
Device handle.
Output
contr1(2)
contr1(4)
Number of output vertices = 0.
Length of intout array = 0.
C BINDING
Procedure Name v_curleft( handle )
Data Types WORD v_curleft ( );
WORD handle;
Input Arguments handle = contrl[6]
9-10
GEM VDI Programmer's Guide
Home Alpha Cursor
ESCAPE 8s HOME
ALPHA CURSOR
This escape moves the alpha cursor to the
home position, usually the upper left character
cell of the display device.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 8.
Device handle.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 0.
C BINDING
Procedure Name
v_curhome( handle )
Data Types
WORD v curhome
WORD handle;
( );
Input Arguments
handle = contrl[6]
9-11
GEM VDI Programmer's Guide
Erase to End of Alpha Screen
ESCAPE 9 s ERASE
TO END OF ALPHA
SCREEN
This escape erases the display surface from
the current alpha cursor position to the end
of the alpha screen. The current alpha cursor
location does not change.
Input
contrl(O) — Opcode = 5.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 0.
contrl(5) — Function id = 9.
contrl(6) — Device handle.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name
v eeos( handle )
Data Types
WORD v_eeos ( )
WORD handle;
Input Arguments
handle = contrl[6]
9-12
GEM VDI Programmer's Guide
Erase to End of Alpha Text Line
ESCAPE 10: ERASE
TO END OF ALPHA
TEXT LINE
This escape erases the display surface from
the current alpha cursor position to the end
of the current alpha text line. The current
alpha cursor location does not change.
Input
contrl(O) —
contrl(l) —
contrl{3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 10.
Device handle.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 0.
C BINDING
Procedure Name
Data Types
Input Arguments
v_eeol( handle )
WORD v_eeol ( ) ;
WORD handle;
handle = contrlL6]
9-13
GEM VDI Programmer’s Guide
Direct Alpha Cursor Address
ESCAPE 11s DIRECT
ALPHA CURSOR
ADDRESS
The Direct Alpha Cursor Address escape moves
the alpha cursor directly to the specified
row and column address anywhere on the display
surface. Addresses beyond the displayable
range of the screen are set to the nearest
value that is within the displayable range of
the screen.
Input
contrl(O) —
Opcode = 5.
contrl(l) —
Number of input vertices = 0.
contrl(3) —
Length of intin array = 2.
contrl(5) —
Function id = 11.
contrl(6) —
Device handle.
intin(O)
Row number (1 to maximum number
of rows).
intin(l)
Column number (1 to maximum
number of columns) .
Output
contrl(2) —
Number
of
output
vertices = 0.
contrl(4) —
Length
of
intout
array = 0.
C BINDING
Procedure Name vs_curaddress( handle, row, column )
Data Types WORD vs__curaddress ( ) ;
WORD handle;
WORD row;
WORD column;
Input Arguments handle = contrl[6]
row = intin[0]
column = intin[l]
9-14
GEM VDI Programmer's Guide Output Cursor Addressable Alpha Text
ESCAPE 12: OUTPUT
CURSOR ADDRESSABLE
ALPHA TEXT
This escape displays a string of alpha text
starting at the current cursor position.
The alpha text attributes currently in effect
determine alpha text attributes.
Input
contrl(O) —
Opcode = 5.
contrl(l) —
Number of input vertices = 0.
contrl(3) —
Number of characters in
character string.
contrl(5) —
Function id = 12.
contrl(6) —
Device handle.
intin
Text string in ADE.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name v_curtext( handle, &string )
Data Types WORD v_curtext ( );
WORD handle?
BYTE stringC];
Input Arguments handle = contrl[6]
string = intin
Note: The BYTE values contain the eight least
significant bits of the intin array.
9-15
GEM VDI Programmer's Guide
Reverse Video On
ESCAPE 13:
REVERSE
VIDEO ON
This escape displays
text in reverse video.
all subsequent alpha
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 13.
Device handle.
Output
contrl(2) —
contrl(4) —
Number
Length
of output vertices = 0.
of intout array = 0.
C BINDING
Procedure Name
Data Types
Input Arguments
v_rvon( handle )
WORD r_von ( );
WORD handle;
handle = contrl[6]
9-16
GEM VDI Programmer's Guide
Reverse Video Off
ESCAPE 14:
REVERSE
VIDEO OFF
This escape displays all subsequent alpha
text in normal video format.
Input
contrl(O) —
contrl(l) —
contr 1(3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 14.
Device handle.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 0.
C BINDING
Procedure Name v_rvoff( handle )
Data Types WORD v_rvoff ( );
WORD handle;
Input Arguments
handle = contrl[6l
9-17
GEM VDI Programmer's Guide Inquire Current Alpha Cursor Address
ESCAPE 15:
INQUIRE CURRENT
ALPHA CURSOR
ADDRESS
This escape returns the current position of
the alpha cursor in row, column coordinates.
Input
contrl(0)
_
Opcode = 5.
contrl(1)
—
Number of input vertices = 0.
contrl( 3)
—
Length of intin array = 0.
contrl(5)
—
Function id = 15.
contr 1{ 6)
Device handle.
Output
contrl(2)
_
Number of output vertices = 0.
contrl(4)
—
Length of intout array = 2.
intout(0)
—
Row number (1 to the maximum
number of rows).
intout (1 )
Column number (1 to the maximum
number of columns) .
C BINDING
Procedure Name
Data Types
Input Arguments
vq_curaddress( handle, &row, &column )
WORD vq curaddress ( );
WORD handle;
WORD row;
WORD handle;
handle = contrl[6]
Output Arguments row = intout[0]
column = intout[l]
9-18
GEM VDI Programmer's Guide
Inquire Tablet Status
ESCAPE 16:
INQUIRE TABLET
STATUS
This escape
of a graphics
other similar
returns the availability status
tablet, mouse, joystick, or
device.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 16.
Device handle.
Output
contrl(2) —
contrl(4) —
intout(O) —
Number of output vertices = 0.
Length of intout array = 1.
Tablet status.
0 = tablet not available
1 = tablet available
C BINDING
Procedure Name status = vq_tabstatus( handle )
Data Types WORD vq_tabstatus ( );
WORD handle;
WORD status;
Input Arguments handle = contrl[6]
Output Arguments status = intoutCO]
9-19
GEM VDI Programmer'
1 s Guide
Hard Copy
ESCAPE 17s HARD
COPY
The device generates a hard copy with this
escape. The escape is device-specific and
copies the physical screen to a printer or
other attached hard copy device.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 17.
Device handle.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 0.
C BINDING
Procedure Name v_hardcopy( handle )
Data Types WORD v_hardcopy ( );
WORD handle;
Input Arguments
handle = contrl[6]
9-20
GEM VDI Programmer's Guide
Place Graphic Cursor at Location
ESCAPE 18: PLACE This escape places a graphic cursor at the
GRAPHIC CURSOR specified location. The cursor is usually a
AT LOCATION cross hair cursor and is of the same type as
that used for Input Locator, Request Mode. If
sample mode input is supported, the application
can use this call to generate the cursor for
Input Locator, Sample Mode. In memory-mapped
devices, the cursor is drawn in XOR mode so GEM
VDI can remove it.
Input
contrl(O) —
Opcode = 5.
contrl(l) —
Number of input vertices = 1.
contrl(3) —
Length of intin array = 0.
contrl(5) —
Function id = 18.
contrl(6) —
Device handle.
ptsin(O) —
x-coordinate of location to
place cursor in current
coordinate system.
ptsin(l)
y-coordinate of location to
place cursor in current
coordinate system.
Output
contrl(2) —
Number
of
output
vertices = 0.
contrl(4) —
Length
of
intout
array = 0.
C BINDING
Procedure Name v_dspcur( handle, x, y )
Data Types WORD v_dspcur ( );
WORD handle;
WORD x, y;
Input Arguments handle = contrl[6]
x = ptsin[0]
y = ptsin[l]
9-21
GEM VDI Programmer's Guide
Remove Last Graphic Cursor
ESCAPE 19: REMOVE This escape removes the last graphic cursor
LAST GRAPHIC placed on the screen.
CURSOR
Input contrl(O)
contrl(1)
contrl(3)
contrl(5)
contrl(6)
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 19.
Device handle.
Output contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name
v rmcur( handle )
Data Types
WORD v_rmcur ( );
WORD handle;
Input Arguments
handle = contrl[6]
9-22
GEM VDI Programmer's Guide
Form Advance
ESCAPE 20: FORM
ADVANCE
This escape is required only for printers.
It advances the printer page. This escape can
be used instead of invoking a Clear Workstation
function if it is desirable to retain the
current printer display list while advancing to
the next page.
Input
contrl(O) — Opcode = 5.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 0.
contrl(5) — Function id — 20.
contrl(6) — Device handle.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name
v_form_adv( handle )
Data Types
WORD v_form_adv( );
WORD handle;
Input Arguments handle = contrl[6]
9-23
GEM VDI Programmer's Guide
Output Window
ESCAPE 21: OUTPUT This escape is required only for printers.
WINDOW It allows the application to request that a
particular rectangular window of the picture be
output to the printer. This escape is similar
to the Update Workstation function, except that
the rectangular area must be specified.
Note that use of this function does not always
guarantee that adjacent pictures will abut.
Pictures will abut with a resolution of one
printer head height.
Input contrl(O)
contrl(l)
contrl(3)
contrl(5)
contr1{ 6)
ptsin(0)
ptsin(l)
ptsin(2)
ptsin(3)
Opcode = 5.
Number of input vertices = 2.
Length of intin array = 0.
Function id = 21.
Device handle.
x-coordinate of corner of window
to be output in NDC/RC.
y-coordinate of corner of window
to be output in NDC/RC.
x-coordinate of corner of
window, diagonally opposite
corner selected in ptsin(O), in
NDC/RC.
y-coordinate of corner of
window, diagonally opposite
corner selected inptsin(l), in
NDC/RC.
Output
contrl(2)
contrl(4)
Number of output
Length of intout
vertices =
array = 0.
0 .
9-24
GEM VDI Programmer’s Guide Output Window
C BINDING
Procedure Name v_output_window( handle, xyarray )
Data Types WORD v_output_window( );
WORD handle;
WORD xyarray[4];
Input Arguments handle = contrl[6]
xyarray[0] = ptsin[0]
xyarray[3] = ptsin[3]
9-25
GEM VDI Programmer's Guide
Clear Display List
ESCAPE 22i CLEAR
DISPLAY LIST
This escape is required only for printers.
It allows the application to request that the
printer display list be cleared. It is similar
to the Clear Workstation function, but does not
cause a form advance on the printer.
Input
contrl(O) — Opcode = 5.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 0.
contrl(5) — Function id = 22.
contrl(6) — Device handle.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name
v_clear_disp_list( handle )
Data Types
WORD v clear disp list( );
WORD handle;
Input Arguments handle = contrl[6]
9-26
GEM VDI Programmer's Guide
Output Bit Image File
ESCAPE 23: OUTPUT This escape is required only for printers.
BIT IMAGE FILE It allows the application to request processing
of a bit image file (see Appendix I, "Bit Image
File Format"). As input parameters, the
application provides a filename and information
on image transformation and page placement.
The application uses three parameters to
control image transformation:
• pixel aspect ratio flag
• x-axis scaling flag
• y-axis scaling flag
The application can set the pixel aspect ratio
flag to preserve or ignore the pixel aspect
ratio defined in the bit image file.
Preserving pixel aspect ratio means the printed
object will have the same aspect ratio it had
on the device on which it was originally drawn.
For example, squares remain squares, and
circles remain circles. Ignoring pixel aspect
ratio means the printed object will not
necessarily have the same aspect ratio it had
on the original device.
The application can set the two axis scaling
flags independently of each other. The flags
determine if the bit image's x or y axes are to
be scaled fractionally or in integer multiples.
The upward boundary of this scaling is an
application-defined rectangle.
If an axis of the bit image is scaled
fractionally, it will exactly fit the
corresponding axis of the scaling rectangle,
with the exception noted below.
If an axis of the bit image is scaled in
integer multiples, it might not exactly fit the
corresponding axis of the scaling rectangle.
If the scaled bit image does not exactly fit
the scaling rectangle, the application can use
alignment parameters to locate the bit image
within the rectangle. These parameters allow
any combination of three vertical and three
horizontal positions.
9-27
GEM VDI Programmer's Guide
Output Bit Image File
Note: The scaled bit image always resides
within the scaling rectangle. If a combination
of preserved pixel aspect ratio, scaling, or
alignment causes the scaled bit image to extend
beyond an edge of the scaling rectangle, GEM
VDI clips the bit image to that edge.
Input contr 1(0) —
contrl(l) —
contrl(3) —
contrl{5) —
contrl(6) —
intin(O)
intin(l)
intin(2)
intin(3)
intin(4)
intin(5)
intin (n+4) —
Opcode = 5.
Number of input vertices = 2.
Length of intin array = length
of filename + 5.
Function id = 23.
Device handle.
Aspect ratio flag.
0 = ignore aspect ratio
1 = honor pixel aspect ratio
Scaling for x-axis.
0 = fractional scaling
1 = integer scaling
Scaling for y-axis.
0 = fractional scaling
1 = integer scaling
Horizontal alignment.
0 = left
1 = center
2 = right
Vertical alignment.
0 = top
1 = middle
2 = bottom
First character of filename.
Last (nth) character of
filename.
9-28
GEM VDI Programmer's Guide
Output Bit Image File
ptsin(O) — Upper left x (if specified).
ptsin(l) — Upper left y (if specified).
ptsin(2) — Lower right x (if specified).
ptsin(3) — Lower right y (if specified).
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name
v_bit_image( handle, filename, aspect,
x scale, y scale, h align,
v align, xyarray )
Data Types
WORD v bit_image();
BYTE filename!];
WORD handle, aspect, x scale, y_scale,
h_align, v_align;
WORD xyarray[];
Input Arguments
handle = contrl[6]
filename = intin[2] . . . intin[n + 1]
aspect = intin[0]
x_scale = intin[l]
y_scale = intin[2]
h_align = intin[3]
v_align = intin[4]
xyarray[0] = ptsin[0]
xyarray[l] = ptsin[l]
xyarray[2] = ptsin[2]
xyarray[3] = ptsin[3]
Note: Bytes for the filename array are mapped
into the corresponding eight least significant
bits of intin. The string must be null-
terminated .
9-29
GEM VDI Programmer's Guide
Select Palette
ESCAPE 60:
PALETTE
SELECT This escape
palette on
screen.
allows the selection of the
the IBM® medium-resolution color
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices = 0.
Length of input array = 1.
Function id = 60.
Device handle.
intin(O)
Color selection.
0 = use red, green, brown
palette (default)
1 = use cyan, magenta, white
palette
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 1.
intout(O) —
Palette selected.
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
selected = vs__palette( handle, palette )
WORD vs_palette( );
WORD handle;
WORD palette;
handle = contrl[6]
palette = intin[0]
selected = intout[0]
GEM VDI Programmer's Guide
Polaroid Palette
POLAROID® PALETTE
Use these escapes to modify the operation of the
Polaroid Palette image recorder. While their
use is not mandatory, they allow construction
of a more efficient user interface.
Palette Driver
These escapes affect a header in the palette
driver. The header contains information on the
current state of the driver and the types of
films it can use. The palette driver contains
exposure tables for five film types. A 25-
character string describes each film type,
stating its manufacturer and its ASA number.
These strings are padded with blanks if the
information requires less than 25 characters.
Seventy-two colors are defined for each film
type. These colors are mapped to an 8 x 9
array with ASCII capitals (A...H), naming the
columns and ASCII digits (1...9), numbering the
rows. A color is selected by its letter and
number. For example, A2 identifies the second
color in column A.
Numbers also identify the port to which the
palette is connected, an f-stop control, and a
resolution control for environments where
memory size prevents the use of the Palette's
full capabilities.
The palette driver normally outputs its
messages directly to the screen. These
messages include error messages and user
prompts.
Error Messages
The palette error messages appear when the
application calls GEM VDI with a function other
than Open Workstation, Close Workstation, or
any of the Escape functions. These messages
can be suppressed with Escape 95. The
application can then use the code returned from
Escape 96 to inform the user of the error
condition.
9-31
GEM VDI Programmer's Guide
Inquire Palette Film Types
ESCAPE 91s
INQUIRE PALETTE
FILM TYPES
This escape returns five strings that
describe the films that the driver is
currently capable of exposing. The strings are
padded with spaces if they have fewer than 25
characters. The strings are returned as ADE
integers in intout.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices =0.
Length of intin array = 0.
Function id = 91.
Device handle.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout = 125.
intout —
5 sets of 25 ADE character
strings.
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vqp_films( handle, film_names )
WORD vqp_fi1ms( );
WORD handle;
WORD film_names[1253;
handle = contrl[6]
film names = intout
Note: Intout words (ADE) are converted to byte
string.
9-32
GEM VDI Programmer's Guide
Inquire Palette Driver State
ESCAPE 92:
INQUIRE PALETTE
DRIVER STATE
This escape returns a block of data that
describes the current state of the driver.
The state can be updated by changing this block
and returning it to the driver with Escape 93.
Input
contrl(0)
contrl(l)
contrl(3)
contrl(5)
contrl(6)
Opcode = 5.
Number of input vertices = 0.
Length of intin = 0.
Function id = 92.
Device handle.
Output contrl(2) —
contrl(4) —
intout(O) —
intout(l) —
intout(2) —
intout(3) —
intout(4) —
intout(5
to 20)
Number of output vertices = 0.
Length of intout array = 20.
Port number.
0 = first comm port
Film number (0...$).
Lightness control ( — 3...3).
Each integer increase
represents opening the aperture
1/3 of an f-stop. A -3 results
in an exposure half as long as
normal, while a 3 doubles the
exposure time.
Interlace flag.
0 = noninterlaced
1 = interlaced
A noninterlaced picture
requires slightly more than
half the memory of an
interlaced picture.
Planes, a number (1...4)
corresponding to number of
colors (2 ...16 ).
Two-character color codes for 8-
color indices stored in ADE
format.
9-33
GEM VDI Programmer's Guide
Inquire Palette Driver State
C BINDING
Procedure Name
Data Types
Input Arguments
Output Arguments
vqp_state( handle, Sport, &film_name,
Slightness, sinterlace, Splanes,
Sindexes )
WORD vqp_state( );
WORD handle;
WORD port;
WORD film_name;
WORD lightness;
WORD interlace;
WORD planes;
WORD indexes[8][2];
handle = contrl[6]
port = intoutCO]
film_name = intoutCl]
lightness = intout[2]
interlace = intout[3]
planes = intout[4]
indexes = intout[5...20]
9-34
GEM VDI Programmer’s Guide
Set Palette Driver State
ESCAPE 93: SET
PALETTE DRIVER
STATE
Input
This escape moves a block of characteristics
into the driver. Use this function after
Escape 92.
contrl(0)
contrl(l)
contrl(3)
contrl(5)
contrl(6)
intin(O)
i nt i n (1)
intin(2)
intin(3)
intin(4)
intin(5
to 20)
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 20.
Function id = 93.
Device handle.
Port number.
0 = first comm port
Film number (0...4).
Lightness control (-3...3).
Each integer indicates opening
the aperture 1/3 an f-stop. A
-3 results in an exposure half
as long as normal, while a 3
doubles the exposure time.
Interlace flag.
0 = noninterlaced
1 = interlaced
Planes (1 to 4), number
corresponds to number of colors
(2 to 16).
Color codes for up to 16 colors.
9-35
GEM VDI Programmer's Guide
Set Palette Driver State
C BINDING
Procedure Name
Data Types
Input Arguments
vsp_state( handle, port, film_num,
interlace, planes, indexes )
WORD vsp_style( );
WORD handle;
WORD port;
WORD film_num;
WORD lightness,
WORD interlace;
WORD planes;
WORD indexes[8][2];
handle = contrl[6]
port = intinCO]
film_num = intin[l]
lightness = intin[2]
interlace = intin[3]
planes = intin[4]
indexes = intin[5-20]
lightness.
9-36
GEM VDI Programmer's Guide
Save Palette Driver State
ESCAPE 94: SAVE
PALETTE DRIVER
STATE
This escape saves the current state of the
driver to disk. The application can change
the default film and index mapping with this
escape.
Input
contrl(0)
contrl(l)
contrl(3)
contrl(5)
contrl(6)
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 94.
Device handle.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
C BINDING
Procedure Name vsp_save( handle )
Data Types WORD vsp_save( );
WORD handle;
Input Arguments
handle = contrl[6]
GEM VDI Programmer's Guide
Suppress Palette Messages
ESCAPE 95:
SUPPRESS PALETTE
MESSAGES
This escape allows the application to
suppress the messages the palette driver
normally outputs to the screen. These messages
are either error messages or user prompts.
Refer to Escape 96 for the messages and their
codes.
Input
contrl(0)
contrl(1)
contrl(3)
contrl(5)
contrl(6)
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
— Function id = 95.
Device handle.
Output
contrl(2 )
contrl(4)
Number of output vertices = 0.
— Length of output array = 0.
C BINDING
Procedure Name
vsp_message( handle )
Data Types
WORD vsp_message( );
WORD handle;
Input Arguments
handle = contrl[6]
9-38
GEM VDI Programmer's Guide
Palette Error Inquire
ESCAPE 96:
PALETTE ERROR
INQUIRE
This escape returns an error code so the
application can notify the user of a problem.
This escape also returns codes for pending user
prompts. The error is not cleared, so a
message can be displayed if such messages are
not suppressed.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 0.
Function id = 96.
Device handle.
Output
contrl(2)
contrl(4)
intout(0)
Number of output vertices = 0.
Length of intout array = 1.
Error codes and pending user
prompts.
0 = no error
1 = open dark slide for print
film
2 = no port at location
specified in driver
3 = palette not found at
specified port
4 = video cable disconnected
5 = operating system does not
allow memory allocation
6 = not enough memory to
allocate buffer
7 = memory not deallocated
8 = driver file not found
9 = driver file found is not
correct type
10= prompt user to process
print film
9-39
GEM VDI Programmer's Guide
Palette Error Inquire
C BINDING
Procedure Name status = vqp_error( handle )
Data Types WORD vqp_error( );
WORD handle;
Output Arguments status = intout[0]
Input Arguments handle = contrl[6]
9-40
GEM VDI Programmer's Guide
Update Metafile Extents
ESCAPE 98: UPDATE The values passed in the ptsin array are
METAFILE EXTENTS used to update the extents information in the
metafile header. The extents information may
be used by some applications to provide a quick
indication of the minimum rectangle which will
bound all primitives output to the metafile.
If the Update Metafile Extents escape is not
used when outputting to the metafile, zeroes
will be written in the extents information
portion of the metafile header.
Input contrl(O)
contrl(1)
contr1(3)
contrl(5)
contrl(6)
ptsin(0)
ptsin(1)
ptsin(2)
ptsin(3)
Opcode = 5.
Number of input vertices = 2.
Length of intin array =0.
Function id = 98.
Device handle.
Minimum x value of the minimum
bounding rectangle.
Minimum y value of the minimum
bounding rectangle.
Maximum x value of the minimum
bounding rectangle.
Maximum y value of the minimum
bounding rectangle.
Output
contrl(2)
contrl(4)
Number of
Length of
output vertices =
intout array = 0.
9-41
GEM VDI Programmer's Guide
Update Metafile Extents
C BINDING
Procedure Name
Data Types
Input Arguments
v_meta_extents(handle, min_x, min_y,
max_x, max y )
WORD v_meta_extents();
WORD handle, min_x, min_y, max_x, max y;
handle = contrl[6];
min_x = ptsin[0];
min y = ptsinCl];
max_x = ptsin[2];
max_y = ptsin[3];
9-42
GEM VDI Programmer's Guide
Write Metafile Item
ESCAPE 99: WRITE The parameters passed in the intin and ptsin
METAFILE ITEM arrays are written to the metafile with an
opcode defining the item as a user-defined
metafile item. Intin (0) should contain a sub¬
opcode that defines what type of user-defined
metafile item is being written. Sub-opcodes
numbered 0 through 100 are reserved; the sub¬
opcode you use to define your metafile item
should be numbered 101 or higher.
Input
contrl(O) —
contrl(l) —
contrl(3) —
contrl(5) —
contrl(6) —
Opcode = 5.
Number of input vertices.
Length of intin array.
Function id = 99.
Device handle.
intin
intin(O)
User-defined information.
Sub-opcode.
ptsin
User-defined information.
Output
contrl(2) —
contrl(4) —
Number of output vertices = 0.
Length of intout array = 0.
C BINDING
Procedure Name
Data Types
Input Arguments
v_write_meta (handle, num__intin, intin,
num_ptsin, ptsin)
WORD v_write_meta();
WORD handle, num_intin, num_ptsin;
WORD intin[num_intin], ptsin[num_ptsin];
handle = contrl[6];
num_intin = contrl[3];
num_ptsin = contrl[l];
intin = intin;
ptsin = ptsin;
9-43
GEM VDI Programmer's Guide
Change GEM VDI Filename
This escape renames a metafile from
GEMFILE.GEM to the specified name and
maintains the file extension .GEM. A path name
and drive can be specified to locate the file
somewhere other than on the current drive and
directory. Contrl(3) contains the length of
the file specification string.
Note: This escape must be called immediately
after Open Workstation, or it has no effect.
It also closes any open metafiles.
Input
contrl(O) —
Opcode = 5.
contrl(l) —
Number of input vertices = 0.
contrl(3) —
Length of intin array = number
of significant characters
[1...74].
contrl(5) —
Function id = 100.
contrl(6) —
Device handle.
intin(0
to n)
Path/filename.
Output
contrl(2) —
Number
of
output
vertices = 0.
contrl(4) —
Length
of
intout
array = 0.
C BINDING
Procedure Name vm_filename( handle, filename )
Data Types WORD vm_filename( );
WORD handle;
BYTE filename[ 3;
Input Arguments handle = contrl[6]
filename = intin[0-n]
Note: The filename must be null-terminated.
End of Section 9
ESCAPE 100:
CHANGE GEM VDI
FILENAME
9-44
Appendix A
GEM VDI Error Messages
Command line syntax error
Description: The GEM VDI command line includes an
illegal character, path, or drive id.
Solution: Check for conformance to your operating
system's conventions for specifying command lines.
Reenter the command line after correcting illegal
entries.
Unable to find ASSIGN.SYS
Description: This message appears when GEM VDI is
unable to find the ASSIGN.SYS file in the specified
location.
Solution: Locate the ASSIGN.SYS file, checking
drives and specific directories and subdirectories.
Reenter the command with the correct location.
Error reading ASSIGN.SYS
Description: The format of the ASSIGN.SYS file is
incorrect. GEM VDI cannot use the file.
Solution: Refer to Appendix B for the correct
format for the ASSIGN.SYS file.
Memory table corrupted
Description: This message appears when memory is
corrupted.
Solution: Reboot your system.
Insufficient memory
Description: This message appears when you try to
reserve memory and not enough memory exists for
allocation.
Solution: If your system has adequate memory to run
GEM VDI, reboot your system.
A-l
GEM VDI Programmer's Guide
GEM VDI Error Messages
Invalid memory block address
Description: This message occurs when the memory is
corrupted.
Solution: Reboot the system.
Drive specification not allowed in ASSIGN.SYS
Description: This error appears when you specify a
drive id in the ASSIGN.SYS file, which is illegal.
Solution: Remove the drive id from the file with
your text editor. Refer to Appendix B for the
correct format of an ASSIGN.SYS file.
Illegal device id in ASSIGN.SYS
Description: This error appears when the device id
number is greater than 32767 or an alphanumeric
string, for example 12D4.
Solution: Refer to Table 1-1 in Section 1 for the
correct numbers to assign to devices, and correct
the ASSIGN.SYS file with your text editor.
Partial record found in ASSIGN.SYS
Description: This error appears when a partial
ASSIGN.SYS entry exists.
Solution: Check your ASSIGN.SYS file for incomplete
device id numbers or filenames. Refer to Appendix B
for the correct ASSIGN.SYS file format.
Invalid filename encountered in ASSIGN.SYS
Description: This error appears when a filename in
the ASSIGN.SYS file is too long or contains illegal
characters.
Solution: Refer to Appendix B for the ASSIGN.SYS
file-naming conventions.
A-2
GEM VDI Programmer's Guide
GEM VDI Error Messages
Requested path not found
Description: This message appears when GEM VDI does
not find the requested path specifying the locations
of the device drivers.
Solution: Re specify the path with the correct path
name.
ASSIGN.SYS file is eapty
Description: This message appears when GEM VDI
finds an empty ASSIGN.SYS file.
Solution: Enter the necessary information with your
text editor. Refer to Appendix B for the necessary
ASSIGN.SYS file contents.
Driver file not found
Description: GEM VDI cannot find the first driver
specified in the ASSIGN.SYS file.
Solution: Make sure that the driver is in the
specified drive, in the correct directory, and in
the correct subdirectory.
Corrupted driver file
Description: GEM VDI finds the device driver, but
is unable to use it.
Solution: Use your distribution disk to make
another copy of the device driver. Try to use the
new copy. Contact your dealer if the device driver
is unusable.
End of Appendix A
A-3
Appendix B
ASSIGN.SYS File
REQUIREMENTS The ASSIGN.SYS file is parsed by the GDOS to
create the assignment table. The assignment
table resides in memory and is referenced when
the application makes an Open Workstation call.
The information required by the ASSIGN.SYS
includes the device id number and the device
driver filename and corresponding faces.
Device Id Nunbers
Table B-l. Device Id Nunbers
Type
Number
Monitor
1-10
Plotter
11-20
Printer
21-30
Metafile
31-40
Camera
41-50
Tablet
51-60
Device Driver The device driver filenames follow specific
Filename naming conventions:
• They must have eight or fewer characters.
• The first character must be alphabetic.
• The file extension must be .SYS.
FORMAT
Figure B-l shows the ASSIGN.SYS file format:
Device
Id
Driver
Filename
Face
Name
01
SCREEN.SYS
FACE1.FNT
Figure B-l. ASSIGN.SYS File Format
B-l
GEM VDI Programmer's Guide
Sample ASSIGN.SYS
SAMPLE ASSIGN.SYS
21 printer, fnt
/comments, if desired
facel.fnt zfacel description
face2.fnt ;face2 description
face3.fnt ;face3 description
01 screen.fnt
/comments, if desired
face4.fnt zface4 description
face5.fnt /face5 description
11 plotter.fnt
/comments, if desired
face6.fnt zface6 description
face7.fnt zface7 description
End of Appendix B
Appendix C
GEM VDI Metafile Format
INTRODUCTION
STANDARD METAFILE
ITEM FORMAT
The metafile driver outputs the information
specified below and performs the described
operations for the indicated opcodes.
Most function requests passed to the metafile
driver result in a standard format metafile item
being written to the metafile buffer. In a
standard format metafile item, the control,
integer, and vertex parameters are written to
the metafile in the following format:
word value
description
0
1
2
3
4.. .
n+4...
contrl[0]
contrlCl]
contrl[3]
contr1[5]
ptsin[0-n]
intin[0-m]
opcode
vertex count
integer parameter count
sub-opcode (or zero)
vertices (if provided)
integer parameters
(if provided)
Note that nothing will be output for the ptsin
or intin information if the vertex count or the
integer parameter count is zero.
The following function requests result in the
output of a standard metafile item:
3 clear workstation
4 update workstation
5, 2 exit alpha mode escape
5, 3 enter alpha mode escape
5,21 advance form
5.21 output window
5.22 clear display list
5.23 output bit image file
6 polyline
7 polymarker
8 text
9 fill area
11, 1 bar
11, 2 arc
11, 3 pie
11, 4 circle
C-l
GEM VDI Programmer's Guide
GEM VDI Metafile Format
NONSTANDARD
METAFILE ITEMS
1 open
workstation
11, 5 ellipse
11, 6 elliptical arc
11, 7 elliptical pie
11, 8 rounded rectangle
11, 9 filled rounded rectangle
11,10 justified graphics text
12 set character height, absolute mode
13 set character baseline vector
14 set color representation
15 set polyline linetype
16 set polyline line width
17 set polyline color index
18 set polymarker type
19 set polymarker height
20 set polymarker color index
21 set text face
22 set text color index
23 set fill interior style
24 set fill style index
25 set fill color index
32 set writing mode
39 set graphic text alignment
104 set fill perimeter visibility
106 set graphic text special effects
107 set character height, points mode
108 set polyline end styles
112 set user-defined fill pattern
113 set user-defined line style pattern
114 fill rectangle
129 set clipping
The metafile file buffer is initialized and
the metafile header is output to it. The
workstation description values normally
returned by an "open workstation" invocation
are returned.
C-2
GEM VDI Programmer's Guide
GEM VDI Metafile Format
Metafile header format:
word description
0 Offffh
1 Length of header in words.
2 100*major version number + minor
version number.
3 NDC/RC transformation mode flag
0 = positive y values ascend from
origin (origin in lower left
corner)
2 = positive y values descend from
origin (origin in upper left
corner)
4-7 Minimum and maximum x and y extent
values for the information
contained in the metafile. If
undefined by the application (see
"Escape 98: Update Metafile
Extents"), all four values are
zero. The values are stored in
the following order: minimum x,
minimum y, maximum x, maximum y.
8-9 Physical page size: page width in
tenths of millimeters, followed by
page height in tenths of
millimeters. If undefined by the
application, both values are zero.
(See Appendix H, "Reserved
Metafile Sub-opcodes.")
10 - 13 The coordinate window which defines
the coordinate system used in the
metafile. If undefined by the
application, all four values are
zero. The values are stored in
the following order: lower left
x, lower left y, upper right x,
upper right y. (See Appendix H,
"Reserved Metafile Sub-opcodes.")
C-3
GEM VDI Programmer’s Guide
GEM VDI Metafile Format
2 close An end-of-metafile opcode is appended to the
workstation metafile file buffer. The metafile file buffer
is flushed and the metafile is closed.
End-of-metafile format:
word
description
1
Offffh
SPECIAL METAFILE
ESCAPES
5, 98 update
metafile extents
The extents information in the metafile
header is updated to indicate the extents passed
in the ptsin array.
5, 99 write
metafile item
escape
A standard format metafile item is written.
The first word of the intin array should
contain a sub-opcode that can be used by an
application to identify the metafile item when
it is read in.
5, 100 change GEM If any information currently exists in the
VDI filename metafile or metafile buffer, the buffer is
escape flushed and the file is closed. The metafile
buffer is reinitialized and rudimentary file
name validation is performed. If the drive,
path, and filename are valid, they are used to
update the file control block (FCB) of the
metafile. The metafile will not actually be
opened until the first buffer needs to be
flushed.
C-4
GEM VDI Programmer's Guide
GEM VDI Metafile Format
INQUIRY FUNCTIONS
5, 1 inquire -1 is returned in both INTOUT parameters to
addressable indicate that cursor addressing is not
alpha character possible,
cells escape
26 inquire color -1 is returned for the color index to
representation indicate that no value is available.
35 inquire The set values are returned.
current polyline
attributes
36 inquire
current polymarker
attributes
37 inquire
current fill
area attributes
38 inquire
current graphic
text attributes
102 extended The appropriate inquiry values are returned,
inquire function
117 inquire
character cell
width
131 inquire
current face
information
End of Appendix C
C-5
GEM VDI Programmer's Guide GEM VDI Metafile Format
Appendix D
Standard Keyboard
GEM VDI defines a standard keyboard so
applications can take advantage of special keys
not defined in the standard, 7-bit ASCII
character set. A 16-bit value is used to
return these characters. The high byte
contains a binary value assigned to each key.
The low byte contains the 7-bit ASCII value, if
such a value is defined, or a zero if the code
is an extended code.
Table D-l. GEM VDI Standard
Keyboard Assignments
High
Byte
Low
Byte
Cha racter
03
00
CNTL 2 (Nul)
IE
01
CNTL A
30
02
CNTL B
2E
03
CNTL C
20
04
CNTL D
12
05
CNTL E
21
06
CNTL F
22
07
CNTL G
23
08
CNTL H
17
09
CNTL I
24
0A
CNTL J
25
0B
CNTL K
26
OC
CNTL L
32
0D
CNTL M
31
0E
CNTL N
18
OF
CNTL O
19
10
CNTL P
10
11
CNTL Q
13
12
CNTL R
IF
13
CNTL S
14
14
CNTL T
16
15
CNTL U
2F
16
CNTL V
11
17
CNTL W
2D
18
CNTL X
15
19
CNTL Y
2C
1A
CNTL Z
1A
IB
CNTL [
2B
1C
CNTL \
IB
ID
CNTL ]
07
IE
CNTL 6
OC
IF
CNTL -
39
20
Space
D-l
GEM VDI Programmer's Guide
Standard Keyboard
Table D-l. (continued)
High
Byte
Low
Byte
Character
02
21
!
28
22
It
04
23
#
05
24
$
06
25
%
08
26
Sc
28
27
'
0A
28
(
OB
29
)
09
2A
*
0D
2B
+
33
2C
OC
2D
-
34
2E
35
2F
/
OB
30
0
02
31
1
03
32
2
04
33
3
05
34
4
06
35
5
07
36
6
08
37
7
09
38
8
OA
39
9
27
3A
:
27
3B
;
33
3C
<
OD
3D
=
34
3E
>
35
3F
7
03
40
@
IE
41
A
30
42
B
2E
43
C
20
44
D
12
45
E
21
46
F
22
47
G
23
48
H
17
49
I
24
4A
J
25
4B
K
26
4C
L
32
4D
M
31
4E
N
18
4F
O
D-2
GEM VDI Programmer's Guide
Standard Keyboard
Table D-l. (continued)
High
Byte
Low
Byte
Character
19
50
P
10
51
Q
13
52
R
IF
53
S
14
54
T
16
55
U
2F
56
V
11
57
W
2D
58
X
15
59
Y
2C
5A
Z
1A
5B
[
2B
5C
\
IB
5D
]
07
5E
A
OC
5F
Underscore
29
60
IE
61
a
30
62
b
2E
63
c
20
64
d
12
65
e
21
66
f
22
67
g
23
68
h
17
69
i
24
6A
j
25
6B
k
26
6C
1
32
6D
m
31
6E
n
18
6F
o
19
70
P
10
71
q
13
72
r
IF
73
s
14
74
t
16
75
u
2F
76
V
11
77
w
2D
78
X
15
79
y
2C
7A
z
1A
7B
2B
7C
IB
7D
29
7E
0E
7F
Rubout (DEL)
D-3
GEM VDI Programmer's Guide
Standard Keyboard
Table D-l. (continued)
High
Byte
Low
Byte
Character
81
00
Alt 0
78
00
Alt 1
79
00
Alt 2
7A
00
Alt 3
7B
00
Alt 4
7B
00
Alt 5
7D
00
Alt 6
7E
00
Alt 7
7F
00
Alt 8
80
00
Alt 9
IE
00
Alt A
30
00
Alt B
2E
00
Alt C
20
00
Alt D
12
00
Alt E
21
00
Alt F
22
00
Alt G
23
00
Alt H
17
00
Alt I
24
00
Alt J
25
00
Alt K
26
00
Alt L
32
00
Alt M
31
00
Alt N
18
00
Alt 0
19
00
Alt P
10
00
Alt Q
13
00
Alt R
IF
00
Alt S
14
00
Alt T
16
00
Alt U
2F
00
Alt V
11
00
Alt W
2D
00
Alt X
15
00
Alt Y
2C
00
Alt Z
3B
00
FI
30
00
F2
3D
00
F3
3E
00
F4
3F
00
F5
40
00
F6
41
00
F7
42
00
F8
43
00
F9
44
00
F10
54
00
Fll
D-4
GEM VDI Programmer's Guide
Standard Keyboard
Table D-l. (continued)
High
Byte
Low
Byte
Character
55
00
F12
56
00
F13
57
00
F14
58
00
F15
59
00
F16
5A
00
F17
5B
00
F18
5C
00
F19
5D
00
F20
5E
00
F21
5F
00
F22
60
00
F23
61
00
F24
62
00
F25
63
00
F26
64
00
F27
65
00
F28
66
00
F29
67
00
F30
68
00
F31
69
00
F32
6A
00
F33
6B
00
F34
6C
00
F35
6D
00
F36
6E
00
F37
6F
00
F38
70
00
F39
71
00
F40
73
00
Ctrl left-arrow
4D
00
right-arrow
4D
36
Shift right-arrow
74
00
Ctrl right-arrow
50
00
down-arrow
50
32
Shift down-arrow
48
00
up-arrow
48
38
Shift up-arrow
51
00
Page down
51
33
Shift Page down
76
00
Ctrl Page down
49
00
Page up
49
39
Shift Page up
84
00
Ctrl Page up
77
00
Ctrl Home
D-5
GEM VDI Programmer's Guide
Standard Keyboard
Table D-l. (continued)
High
Byte
Low
Byte
Character
47
00
Home
47
37
Shift Home
52
00
Insert
52
30
Shift Insert
53
00
Delete
53
2E
Shift Delete
72
00
Ctrl Print Screen
37
2A
Print Screen
01
IB
Escape
0E
08
Backspace
82
00
Alt -
83
00
Alt =
1C
0D
CR
1C
0A
Ctrl CR
4C
35
Shift Num Pad 5
4A
2B
Num Pad -
4E
2B
Num Pad +
OF
09
Tab
OF
00
Backtab
4B
00
left-arrow
4B
34
Shift left-arrow
4F
00
End
4F
31
Shift End
75
00
Ctrl End
End of Appendix D
Appendix E
Processor-Specific Data
8086-SPECIFIC DATA
Registers and
Interrupts
Note: GEM VDI supports Concurrent™ operating
systems that support DOS calls of versions 2.0
and above.
The address of the Parameter Block is passed
in two 16-bit registers (Ds:Dx for the 8086)
from the application program to GEM VDI. Pass
0473h in the Cx register. The interrupt is EF.
Exchange Mouse For 8086-based microcomputers, the
Movement Vector application-dependent code is invoked via a CALL
FAR (CALLF) instruction. On entry, the Bx
register contains the new x position of the
mouse. The Cx register contains the new y
position of the mouse. When complete, the
application-dependent code should do a RETURN
FAR (RETF) instruction with the x,y position of
the mouse the driver is to store in Bx, Cx.
Exchange Button
Change Vector
For 8086-based processors, the application
code is invoked via a CALL FAR (CALLF)
instruction with Ax containing the mouse button
keys. Keys are encoded by the same rules that
apply to the Sample Mouse Button State
function. When complete, the application-
dependent code should do a RETURN FAR (RETF)
instruction with the mouse button state the
driver is to store in Ax.
E—1
GEM VDI Programmer's Guide
8086-specific Data
Exchange Cursor
Change Vector
For 8086-based machines, the application-
dependent code is invoked with a CALL FAR
(CALLF) instruction. Upon entry, the Bx
register contains the x position and the Cx
register the y position. If the application-
dependent code does not draw its own cursor, a
CALL FAR should be performed to the address
returned in contrl(9) and contrl(lO) with the
x,y position at which to draw the cursor in Bx,
Cx. This causes GEM VDI to draw a cursor.
When complete, the application should perform a
RETURN FAR (RETF) instruction.
Exchange Timer
Interrupt Vector
For 8086-based processors, the application-
dependent code is invoked with a CALL FAR
(CALLF) instruction. When complete, the
application should perform a RETURN FAR (RETF)
instruction.
E-2
GEM VDI Programmer's Guide
68000-specific Data
68000-SPECIFIC DATA
Registers and The address of the Parameter Block is passed
Interrupts in one 32-bit register, D0.1 for 68K from the
application program to GEM VDI. Dl.w contains
the function code 115.
For CP/M-68K, GEM VDI is invoked via TRAP 2.
For other 68K operating systems that support
GEM VDI, the TRAP is identified in the
operating system's manual.
Exchange Mouse For 68000-based microcomputers, the
Movement Vector application-dependent code is invoked via a JUMP
TO SUBROUTINE (JSR) instruction. On entry, the
DO.w register contains the new x position of
the mouse. The Dl.w register contains the new
y position of the mouse. When complete, the
application-dependent code should do a RETURN
FROM SUBROUTINE (RTS) instruction with the x,y
position of the mouse the driver is to store in
DO.w, Dl.w.
Exchange Button For 68000-based processors, the application
Change Vector code is invoked via a JUMP TO SUBROUTINE (JSR)
instruction with DO.w containing the mouse
button keys. Keys are encoded by the same
rules that apply to the Sample Mouse Button
State function. When complete, the
application-dependent code should do a RETURN
FROM SUBROUTINE (RTS) instruction with the
mouse button state the driver should store in
DO.w.
E-3
GEM VDI Programmer's Guide
68000-specific Data
Exchange Cursor
Change Vector
Exchange Timer
Interrupt Vector
For 68000-based machines, the application-
dependent code is invoked with a JUMP TO
SUBROUTINE (JSR) instruction. Upon entry, the
DO.w register contains the x position and the
Dl.w register the y position. If the
application-dependent code does not draw its
own cursor, a JUMP TO SUBROUTINE (JSR)
instruction should be performed to the address
returned in contrl(9) and contrl(lO) with the
x,y position at which to draw the cursor in
DO.w and Dl.w. This causes GEM VDI to draw a
cursor. When complete, the application should
perform a RETURN FROM SUBROUTINE (RTS)
instruction.
For 68000-based processors, the application-
dependent code is invoked with a JUMP TO
SUBROUTINE (JSR) instruction. When complete,
the application should perform a RETURN FROM
SUBROUTINE (RTS) instruction.
End of Appendix E
E-4
Appendix F
Character Sets
The system fonts provided with GEM VDI are
illustrated in Figure F-l and F-2. Figure F-l
shows the USASCII character set. Figure F-2
shows the additional characters included to
form the international character set.
Note that external fonts (those which are
dynamically loaded) do not include characters
for decimal equivalents 0 through 31.
F-l
GEM VDI Programmer's Guide
Character Sets
HFXA |
DECIMALl Q
0
0
1
1
2
2
3
3
5
5
6
6
7
7
8
8
9
9
10
A
11
B
12
C
13
D
14
E
15
F
32
48
2
3
BLANK
(SPACE)
0
!
•
1
2
#
3
$
4
%
5
&
6
5
7
n
8
B
9
□B
+
•
?
?
<
=
.
>
/
•
5 6 7
P P
A Q a q
B R
C S c s
D T d
E U e u
F V f v
G W g w
H X h x
I Y i y
J Z
K
L \
M
z
k {
m
}
n
o
A
F-2
GEM VDI Programmer's Guide
Character Sets
0
0
1
1
2
2
3
3
5
5
6
6
7
7
8
8
9
9
10
A
11
B
12
C
13
D
14
E
15
F
e IO
160
176
A
B
f
a
a
/
i
6
/
o
0
/
u
0
n
oe
N
CE
a
\
A
o
A
•
6
i
■
~n
B
y 2
+
X A
%
«
»
TM
a
0 ±
>
7r <
0 °
0
ft
5
§ n
<t>
G
F-3
Appendix G
Font Format
INTRODUCTION
The system fonts and external fonts used in GEM
VDI are composed of four parts: the font data,
a font header, a character offset table, and a
horizontal offset table.
FONT DATA
The font data is organized as a single raster
area. The area's height equals the font height
and its width equals the sum of the character
widths.
The top scan line of the first character in the
font is aligned to a byte boundary. The top
scan line of the second character is abutted to
the first character and is not necessarily
byte-aligned. That is, the end of any
character and the beginning of the following
character often occur within the same byte; no
byte alignment occurs within the font form.
Bit padding occurs only at the end of a scan
line. Each scan line in the font form begins
on a word boundary. The number of bytes from
the beginning of one scan line to the beginning
of the next is called the form width. The
number of scan lines required to draw any
character is called the form height.
A flag within the font header indicates the
orientation of bytes within a word in the font
data. If the flag is cleared, the font data is
in a format such that the low byte of a word
occurs in memory before the high byte
(Intel® format). If the flag is set, the high
byte precedes the low byte in memory.
FONT HEADER The font header contains information that
describes global aspects of the font. For
example, the name of the face, the font size,
the minimum and maximum characters in the font,
and any other data that applies to every
character of the font are global aspects of
that font. The format of the font header is
shown in Table G-l.
G-l
GEM VDI Programmer's Guide
Font Header
Table G-l. Font Header Format
Byte
Number
Description
0 -
• 1
face identifier (see the Set
Text Face function)
2 -
■ 3
font size in points
4 -
• 35
face name (see the Inquire
Face Name and Index
func tion)
36
- 37
lowest ADE value in the face
38
- 39
highest ADE value in the face
40
- 41
*top line distance
42
- 43
*ascent line distance
44
- 45
*half line distance
46
- 47
*descent line distance
48
- 49
*bottom line distance
50
- 51
width of the widest character
in the font
52
- 53
width of the widest character
cell in the face
54
- 55
left offset (see the Inquire
Current Face Information
function)
56
- 57
right offset (see the Inquire
Current Face Information
function)
58
- 59
thickening: the number of
pixels by which to widen
thickened characters
60
- 61
underline size: the width
(in pixels) of the underline
G-2
GEM VDI Programmer's Guide
Font Header
Table G— 1. (continued)
Byte Number
Description
62 - 63
lightening mask: the mask
used to drop pixels out when
lightening; usually 5555H
64 - 65
skewing mask: the mask that
is rotated to determine when
to perform additional
rotation on the character to
perform skewing; usually
5555H
66 - 67
flags:
bit 0 set if default
system font
bit 1 set if horizontal
offset tables
should be used
bit 2 byte-swap flag (see
"Font Data”)
bit 3 set if mono-spaced
font
68 - 71
pointer to the horizontal
offset table
72 - 75
pointer to the character
offset table
76 - 79
pointer to the font data
80 - 81
form width (see "Font Data")
82 - 83
form height (see "Font Data")
84 - 87
pointer to the next font (set
by the driver)
* - Distances are measured relative to the
character baseline and are always a positive
value (magnitude rather than offset).
G-3
GEM VDI Programmer's Guide
Character Offset Table
CHARACTER OFFSET
TABLE
HORIZONTAL OFFSET
TABLE
The character offset table is used to index
into the font data and to determine the width of
specific characters in the font. It is indexed
by relative character value (the ADE value of
the desired character, minus the lowest ADE
value in the font) and yields the offset from
the base of the font data to the beginning of
the character definition. The difference
between the offset to a character and the
offset to the following character gives the
width of the character. Note that the
character offset table includes one more entry
than the number of characters in the font so
that a width may be obtained for the final
character in the font.
Note: The character offset table is required
even for mono-spaced fonts.
The horizontal offset table is indexed by
relative character value and yields any
additional positive or negative spacing
necessary before outputting the character. The
horizontal offset table often does not exist.
Whether it exists or not is indicated by the
horizontal offset table bit in the flags word
of the font header.
End of Appendix G
Appendix H
Reserved Metafile Sub-opcodes
METAFILE SOB- The following sub-opcodes are reserved for
OPCODES FOR USE use by the GEM Output application. GEM VDI
WITH GEM OUTPUT defines sub-opcodes for the following sub¬
functions :
• Physical Page Size
• Coordinate Window
The opcodes are used by the GEM Output
application to define how large a picture is to
be rendered on the output page and also to
define a transformation which maps from the
metafile coordinate system to the output
dev ice.
The two GEM Output metafile sub-opcodes result
in an update of the metafile header. The
opcodes are not actually written to the body of
the metafile.
PHYSICAL PAGE SIZE This sub-function defines the size of the area
to be output to. All of the data in the
coordinate window is mapped to this area. If
no physical page size is defined, the Output
application will attempt a best fit on the
target device, assuming that "pixels" in the
metafile are square.
Input contrl(O)
contrl(l)
contr1(3)
contrl(5)
contr1(6)
intin(0)
intin(1)
intin(2)
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 3.
Function id = 99.
Device handle.
Sub-opcode number = 0.
Page width in tenths of
mi Hi me ter.
Page height in tenths of
millimeter.
Output
contr1(2)
contr1(4)
Number of output vertices = 0.
Length of intout array = 0.
GEM VDI Programmer's Guide
Coordinate Window
COORDINATE WINDOW This sub-function defines the coordinate system
used in the metafile. All of the data in the
defined coordinate window is mapped to the area
defined by the physical page size sub-function.
The coordinate window defaults to NDC space (0
to 32K). The location of the origin, (0, 0),
depends on the coordinate space set when the
metafile was opened (see "Open Workstation").
For example, if the Open Workstation function
was invoked specifying raster coordinate space,
the origin would be located in the upper left
corner of the display surface.
Note that the window corner information must be
specified as the lower left and upper right
corners. Arbitrary opposing corners will not
convey enough information.
Input
contrl(0) —
Opcode = 5.
contrl(l) —
Number of input vertices = 0.
contrl(3) —
Length of intin array = 5.
contrl(5) —
Function id = 99.
contrl(6) —
Device handle.
intin(0)
Sub-opcode = 1.
intin(l)
x-coordinate of lower left
corner of window.
intin(2)
y-coordinate of lower left
corner of window.
intin(3)
x-coordinate of upper right
corner of window.
intin(4) —
y-coordinate of upper right
corner of window.
Output
contrl(2) —
contrl(4) —
Number of output
Length of intout
vertices =
array = 0.
0 .
H-2
GEM VDI Programmer 1 s Guide
Metafile Sub-opcodes with GEM Draw
METAFILE SUB¬
OPCODES FOR USE
WITH GEM DRAW
The following sub-opcodes are reserved for
use by the GEM Draw™ application. GEM VDI
defines the sub-opcodes for the following sub¬
functions :
• Start Group
• End Group
• Set Attribute Shadow On
• Set Attribute Shadow Off
• Start Draw Area Type Primitive
• End Draw Area Type Primitive
• Set No Line Style
START GROUP This sub-function indicated the beginning of a
group of primitives for the GEM Draw
application. All subsequent primitives which
occur before the next End Group sub-opcode will
be regarded as a group by the GEM Draw
application.
Input
contrl(0)
contrl(l)
contr1(3)
contrl(5)
contrl(6)
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 1.
Function id = 99.
Device handle.
intin(0)
Sub-opcode number = 10.
Output
contrl(2)
contrl(4)
Number of
Length of
output vertices =
intout array = 0.
0 .
H-3
GEM VDI Programmer's Guide
End Group
END GROUP
This sub-function indicated the end of a group
of primitives for the GEM Draw application.
Input
contrl(0 )
contrl(1 )
contrl( 3)
contrl(5)
contrl( 6)
— Opcode = 5.
— Number of input vertices = 0.
Length of intin array = 1.
Function id = 99.
Device handle.
intin(O)
Sub-opcode number = 11.
Output
contr1( 2 )
contrl(4)
Number of output vertices = 0.
Length of intout array =0.
SET MO LINE STYLE
This sub-function is used by GEM Draw to
indicate that subsequent area type primitives
are not to be outlined. The effects of this
sub-opcode are cancelled by any subsequent set
line style opcode.
Input
contr1(0)
contrl(l)
contr1( 3 )
contrl(5)
contrl{ 6 )
— Opcode = 5.
— Number of input vertices =0.
— Length of intin array = 1.
— Function id = 99.
— Device handle.
intin(0 )
— Sub-opcode number = 49.
Output
contr1( 2)
contr1( 4)
— Number of output vertices = 0.
— Length of intout array = 0.
H-4
GEM VDI Programmer's Guide
Set Attribute Shadow On
SET ATTRIBUTE This sub-function is used by GEM Draw to
SHADOW ON indicate that all subsequent primitives which
occur before the next Set Attribute Shadow Off
sub-opcode should be ignored because they are
used to draw a drop shadow for the first
primitive immediately following the Set
Attribute Shadow Off sub-opcode. Internally,
GEM Draw assigns a shadowed attribute to the
first primitive following the Set Attribute
Shadow Off sub-opcode and performs its own
shadow drawing. All attribute information
which occurs between Set Attribute Shadow On
and Set Attribute Shadow Off will continue to
be processed.
Note that GEM Draw will not drop shadows from
text or from polylines consisting of only two
vertices.
Input contr1(0)
contrl(l)
contrl(3)
contrl(5)
contrl(6)
intin(0)
Opcode = 5.
Number of input vertices = 0.
Length of intin array = 1.
Function id = 99.
Device handle.
Sub-opcode number = 50.
Output
contr1(2)
contrl(4)
Number of
Length of
output vertices =
intout array = 0.
0 .
H-5
GEM VDI Programmer's Guide
Set Attribute Shadow Off
SET ATTRIBUTE
SHADOW OFF
This sub-function indicates to GEM Draw the
end of primitives used to draw a drop shadow of
the first primitive following this sub-opcode.
Input
contrl(O) — Opcode = 5.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 1.
contrl(5) — Function id = 99.
contrl(6) — Device handle.
intin(O) — Sub-opcode number = 51.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
START DRAW AREA
This sub-function indicates to GEM Draw that
TYPE PRIMITIVE
an area type primitive block follows. GEM Draw
will use the vertices of the first primitive
(anything except text) which follows this sub¬
opcode to define a GEM Draw area type
primitive. All other primitives encountered
before the next End Draw Area Type Primitive
sub-opcode will be ignored.
Input
contrl(O) — Opcode = 5.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 1.
contrl(5) — Function id = 99.
contrl(6) — Device handle.
intin(O) — Sub-opcode number = 80.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
H-6
GEM VDI Programmer's Guide
End Draw Area Type Primitive
END DRAW AREA
TYPE PRIMITIVE
This sub-function indicates to GEM Draw the
end of an area type primitive block.
Input
contrl(O) — Opcode = 5.
contrl(l) — Number of input vertices = 0.
contrl(3) — Length of intin array = 1.
contrl(5) — Function id = 99.
contrl(6) — Device handle.
intin(O) — Sub-opcode number = 81.
Output
contrl(2) — Number of output vertices = 0.
contrl(4) — Length of intout array = 0.
End of Appendix H
Appendix I
Bit Image File Format
INTRODUCTION A GEM VDI bit image file is a file with
extension .IMG and contains information which
may be used to re-create a picture from its bit
(pixel) image. The file consists of a header
and raw pixel information. The pixel
information may be encoded in a variety of
formats.
HEADER FORMAT The bit image file header consists of sixteen
words. Each word is in machine-dependent
format (for example, oriented with low byte
first for Intel 808x processors or with high
byte first for Motorola 68000 processors).
Word
Contents
0
1
2
3
4
5
6
7
8
9
upper left x of the bit image
upper left y of the bit image
lower right x of the bit image
lower right y of the bit image
source device page width
source device page height
source device pixel width in microns
source device pixel height in microns
bits per pixel
16 reserved for future use (zero)
DATA FORMAT Pixel data may be encoded in any of four
formats. All four formats may occur within the
same bit image file. The four formats include:
• run-length encoding
• extended run-length encoding
• raster encoding
• raster-run encoding
The data portion of the bit image file is
encoded as bytes of information.
1-1
GEM VDI Programmer's Guide
Data Format
Each of the four formats except for run-length
encoding (the default) consists of a single
packet prefaced by an opcode. A run-length
encoded packet has no preface opcode.
Run-length
Encoding
This is the default pixel data format and
requires no identifying opcode (i.e., when an
extended run, a raster stream, or a raster-run
stream ends, run-length encoding is in effect).
A run-length packet consists of two bytes of
information: a run length and a pixel value.
The run length must be less than 128 and the
pixel value must be less than 256. A run of
pixels may wrap across lines.
Run-length packet:
byte 0 run length
byte 1 pixel value
Extended Run-
length Encoding
When a run is longer than 127 pixels, the
extended run-length encoding may be used. An
extended run includes a count of 128 pixel
runs. For example, if a run exists which is
1000 pixels in length, it would be most
efficient to encode it as an extended run of
length seven (896 pixels) followed by a
standard run of length 104.
Extended run-length packet:
byte 0 opcode = -1
byte 1 extended run length
byte 2 pixel value
1-2
GEM VDI Programmer's Guide
Extended Run-length Encoding
Raster Encoding Data which is not efficiently encoded in any of
the other formats may be raster-encoded. A
raster stream is built which consists of packed
pixel values. Pixel values are packed into
bytes such that each pixel value occupies the
number of bits indicated in the "bits per
pixel" parameter of the file header and such
that a pixel value packed into a higher order
portion of the byte occurs before the adjacent
lower order pixel value. Pixel values should
be packed across byte boundaries when
necessary.
For example, assume that five pixels are to be
encoded in raster format and that their pixel
values are, respectively, one, two, three,
four, and five. Assume that there are three
bits per pixel. The resulting raster stream
would be as follows:
pixels: 12345
bits: 001 010 011 100 101 x
byte 0 byte 1
The bit designated "x" may be either 0 or 1.
Raster packet:
byte 0 opcode = -2
byte 1 number of pixels in the stream
byte 2 packed pixel values
Raster-run encoding may be used to run-
length encode groups of raster streams. For
example, if a pattern of pixels repeats a
number of times, the pattern may be packed into
a raster stream (see "Raster Encoding" above)
and a repeat count may be indicated.
Raster-run packet:
byte 0 opcode = -3
byte 1 pattern repeat count
byte 2 number of pixels in the stream
byte 3 packed pixel values
End of Appendix I
Raster-run
Encoding
1-3
Glossary
ASSIGN.SYS
coordinate scaling
coordinate systems
default device
driver
device driver
device handle
device
identification
number
Text file created by the driver installation
program. Associates device identification (id)
numbers with specific device driver files so
that devices can be referred to by type within
the application program. The ASSIGN.SYS file
can be modified using any text editor.
Converting points from one space or coordinate
system to another. In GEM VDI, this term
refers to the change between Normalized Device
Coordinates (NDC) and Raster Coordinates (RC).
Cartesian space in which points are defined.
GEM VDI supports two systems: Normalized Device
Coordinates (NDC) and Raster Coordinates (RC).
First driver named in the ASSIGN.SYS
file. It must be the largest driver that will
be loaded during a graphics session.
Device-dependent portion of GEM VDI that
translates standard device-independent graphics
operations to device-specific command sequences
for a particular device.
Unique value used to identify which workstation
the GEM VDI function should use. GEM VDI
assigns these numbers at Open Workstation.
Id number assigned to a device in the
ASSIGN.SYS file. Each device in the
ASSIGN.SYS file has a unique device number
assigned to it.
Glossary-1
GEM VDI Programmer's Guide
Glossary
face
font
function code
graphics command
graphics device
Graphics Device
Operating System
(GDOS)
Generalized
Drawing
Primitive (GDP)
Graphics
Environment Manager
Virtual Device
Interface (GEM VDI)
Graphical Kernel
System (GKS)
graphics
primitives
Letter style, such as Times Roman. GEM VDI
stores the definition of each style in a data
file. When an application calls for the use of
a particular text face, GEM VDI uses the
definition to form the text characters on the
specified graphics device.
Collection of characters all in one typeface, a
subset of face.
See operation code.
Command that loads the GDOS into memory.
Hardware that accepts graphics input (mouse or
keyboard, for example) or displays graphics
output (screen, printer, or plotter, for
example) .
Device-independent portion of GEM VDI that
services graphics requests and calls the
device driver to send commands to graphics
dev ices.
Display function used to address special
device capabilities such as curve drawing.
GEM VDI supports the following GDPs: bar, arc,
pie, circle, ellipse, elliptical arc,
elliptical pie, rounded rectangle, filled
rounded rectangle, and justified graphics text.
Not all devices support all GDPs.
Graphics extension to microcomputer opera¬
ting systems. The GEM VDI makes it possible
to run graphics applications on a micro¬
computer.
International standard for the programming
interface to graphics from an application
program.
Basic graphics operations performed by GEM
VDI, for example, drawing lines, markers, and
text strings.
Glossary-2
GEM VDI Programmer's Guide
Glossary
hot spot
metafile
Memory Form
Definition Block
(MFDB)
Normalized Device
Coordinate (NDC)
space
normalized
device coordinates
(NDC)
operation codes
(opcodes)
pixel (pixel
element)
Area of the cursor that covers the pixel whose
x,y location is returned during locator input.
For example, the hot spot on a cross hair
cursor is the intersection point of the two
lines making up the cross.
Data file containing a picture description. The
GEM VDI metafile can be sent to any device or
used to exchange a picture between two
applications.
Block of memory that defines a raster area.
An MFDB includes the following raster area
information:
• pointer to the memory address of the upper
left corner of the first plane
• height and width, in pixels
• width, in words
• number of planes
• flag to indicate if format is standard or
device-dependent
• locations reserved for future use
Uniform virtual space by which a graphics
application program can pass graphics
information to a device. The GDOS maps NDCs to
RCs. NDC space has its origin in the lower
left corner.
Any point in NDC space.
Passed to GDOS as part of a parameter list.
The opcode indicates which graphics operation is
requested.
Smallest element of a display surface that
can be independently referenced.
Glossary-3
GEM VDI Programmer's Guide
Glossary
raster area
Raster
Coordinate (RC)
space
Raster Coordinate
(RC)
raster functions
transformation
node
Virtual Device
Interface (VDI)
virtual screen
Rectangular blocks of either bits in memory or
pixels on a physical device. Rasters are the
steps between pixels.
Actual device units. Raster coordinate space
has its origin in the upper left corner. Its
limits are determined by the resolution of the
specific device.
Point in RC space.
Functions that operate on pixels either
individually or in groups.
Determines which coordinate system the
application is using, NDC or RC. If NDC, the
transformation mode determines how the GDOS
maps the NDCs to the RCs with two methods:
full NDC to RC space or uniform NDC to RC
space.
Standard interface between device-dependent
and device-independent code in a graphics
environment. The GEM VDI makes all device
drivers appear identical to the calling
program.
Block of memory that can be addressed as if it
were a memory-mapped display.
End of Glossary
Glossary-4
Index
A
architecture, 1-2
B
bit image file format, 1-1
BYTE, 2-1
C
Cell Array function, 4-11
character offset, G-4
Close Virtual Screen
Workstation function, 3-13
Close Workstation function, 3-9
control array, 1-5
coordinate window, H-l, H-2
Copy Raster
Opaque function, 6-7
Transparent function, 6-9
D
data format with bit image
files, 1-1
device drivers, 1-2
device handle, 1-4
device id number, 1-4
E
error messages, A-l
escape
alpha cursor down, 9-1, 9-8
alpha cursor home, 9-11
alpha cursor left, 9-1, 9-10
alpha cursor right, 9-1, 9-9
alpha cursor up, 9-1, 9-7
clear display list, 9-2, 9-26
direct alpha cursor address,
9-1, 9-14
enter alpha mode, 9-1, 9-6
erase to end of alpha screen,
9-1, 9-12
erase to end of alpha text
line, 9-1, 9-13
exit alpha mode, 9-1, 9-5
form advance, 9-2, 9-23
change GEM VDI filename, 9-44
hard copy, 9-2, 9-20
home alpha cursor, 9-1, 9-11
inquire addressable alpha
character cells, 9-1, 9-4
inquire current alpha cursor
address, 9-2, 9-18
inquire palette driver
state, 9-2, 9-33
inquire palette film
types, 9-2, 9-32
inquire tablet status,
9-2, 9-19
output bit image file, 9-27
output cursor addressable
alpha text, 9-1, 9-15
output window, 9-2, 9-24
palette error inquire,
9-2, 9-39
place graphic cursor at
location, 9-2, 9-21
remove last graphic
cursor, 9-2, 9-22
reverse video off, 9-2,
9-17
reverse video on, 9-1,
9-16
save palette driver state,
9-2, 9-37
select palette, 9-2,
9-30
set palette driver state,
9-2, 9-35
suppress palette
messages, 9-2, 9-38
update metafile extents, 9-41
write metafile item,
9-2, 9-43
Exchange Button Change
Vector function, 7-27
Exchange Cursor Change
Vector function, 7-31
Exchange Mouse Movement
Vector function, 7-29
extended run-length encoding,
1-2
external fonts, G-l
F
Filled Area function, 4-8
Filled Rounded Rectangle
function, 4-25
font data, G-l
font form, G-l
Index-1
font format, G-l
font header, G-l
Form Advance
function, 9-23
function code
escape, 9-1
function
Bar, 4-8
Cell Array, 4-11
Circle, 4-28
Close Virtual Screen
Workstation, 3-13
Close Workstation, 3-9
Copy Raster, Opaque, 6-7
Copy Raster, Transparent, 6-9
Exchange Button Change
Vector, 7-27
Exchange Cursor Change Vector
function, 7-31
Exchange Mouse Movement
Vector, 7-30
Filled Area, 4-8
Filled Rounded Rectangle,
4-25
Get Pixel, 6-13
Input Locator, Request Mode,
7-3
Input Locator, Sample Mode,
7-6
Input String, Request Mode,
7-15
Input String, Sample Mode,
7- 17
Input Valuator, 7-9
Inquire Current Face
Information, 8-21
Inquire Face Name and Index,
8- 19
Justified Graphics Text, 4-27
Load Fonts, 3-16
Open Virtual Screen
Workstation, 3-10
Open Workstation, 3-1
Polyline, 4-1
Polymarker, 4-4
Rounded Rectangle, 4-25
Sample Keyboard State
Information, 7-33
Sample Mouse Button State,
7-26
Set Graphic Text Special
Effects, 5-27
Set Input Mode, 7-1
Set Mouse Form, 7-19
Set Polyline End Styles, 5-12
Set Text Face, 5-24
Set User-defined Fill
Pattern, 5-37
Text, 4-6
Unload Fonts, 3-17
Update Workstation, 3-15
G
GDOS, 1-2
GDP
Arc & Pie function, 4-19
Bar function, 4-18
Circle function, 4-21
Ellipse, 4-24
Elliptical Arc and Pie, 4-22
GEMVDI command, 2-19
Get Pixel function, 6-13
Graphics Device Operating
System, See GDOS
H
hard copy escape, 9-20
header format with bit image
files, 1-1
hide cursor escape, 7-25
horizontal offset table, G-4
I
Input Locator
Request Mode function, 7-3
Sample Mode function, 7-6
input parameters array, 1-5
input point coordinates, 1-5
Input String
Request Mode function, 7-15
Sample Mode function, 7-17
Input Valuator function, 7-9
inquire cell array, 8-23
inquire character cell width,
8-17
inquire color representation,
8-5
Inquire Current Face
Information function, 8-21
Inquire Face Name and Index
function, 8-19
Inquire Palette Driver State
Escape, 9-33
Inquire Palette Film Types
Escape, 9-32
Index-2
inquire text extent, 8-15
interrupt for 68K, E-3
interrupt for 8086, E-l
J
justified graphics text, 4-27
L
Load Fonts function, 3-16
M
memory requirements, 2-20
metafile sub-opcodes, H-l, H-3
multiple workstations, 1-4
N
NDC, 1-4, 1-6
normalized device coordinates,
1- 4, 1-6
O
Open Virtual Screen Workstation
function, 3-10
Open Workstation function, 3-1
output parameters, 1-5
output point parameters, 1-5
Output Window
Escape, 9-24
P
Palette Error Inquire
Escape, 9-39
physical page size, H-l
plotter functions, 2-13
Polaroid Palette Escapes, 9-31
Polyline function, 4-1
Polymarker function, 4-4
R
registers for 68K, E-3
registers for 8086, E-l
required functions for
printers, 2-11
required functions for screens,
2- 9
reserved metafile sub-opcodes,
H-l
Rounded Rectangle function,
4- 25
run-length encoding, 1-1, 1-2
S
Sample Keyboard State
Information function, 7-33
Sample Mouse Button State
function, 7-26
Save Palette Driver State
Escape, 9-37
scan line, G-l
Select Palette
Escape, 9-30
set character baseline vector,
5- 22
set character cell height
points mode, 5-18, 5-20
set character height
absolute mode, 5-18
Set Clipping Rectangle
function, 3-19
set color representation, 5-4
set fill color index, 5-35
set fill interior style, 5-32
set fill perimeter visibility,
5-36
set fill style index, 5-33
set graphic text alignment,
5-30
set graphic text color index,
5-26
set graphic text special
effects, 5-27
Set Input Mode function, 7-1
Set Mouse Form function, 7-19
Set Palette Driver State
Escape, 9-32
set polyline color index, 5-11
Set Polyline End Styles
function, 5-12
set polyline line type, 5-6
set polyline line width, 5-9
set polymarker color index,
5-17
set polymarker height, 5-16
set polymarker type, 5-14
set text color index, 5-24
Set Text Face function, 5-24
Set User-defined Fill Pattern
function, 5-33
set user-defined line style,
5-8
Index-3
set writing mode, 5-1
show cursor, 7-23
stack requirements, 2-20
sub-opcodes, H-l
Suppress Palette Messages
Escape, 9-38
system fonts, G-l
T
Text function, 4-6
transforming points, 1-6
D
Unload fonts function, 3-17
Update Workstation function,
3-15
V
VDI, 1-5
Virtual Device Interface, 1-5
VDI, 1-5
W
WORD, 2-1
Write Metafile Item Escape,.
9-43
Index-4
GEM VDI Function Reference Card
Op Code
Function Name-Section
Procedure Name
1
Open Workstation-1
v_opnwk(work in, 8(handle, work out);
2
Close Workstation-1
v_clswk(handle);
3
Clear Workstation-1
vclrwk(handle);
4
Update Workstation-1
v updwk(handle);
5
Escapes
5-1
Inquire Addressable Character Cells-9
vq_chcells(handle, 8irows, 8icolumns);
5-2
Exit Alpha Mode-9
v_exit_ c ur(handl e );
5-3
Enter Alpha Mode-9
ventercur(handle);
5-4
Cursor Up-9
vcurup(handle);
5-5
Cursor Down-9
vcurdown(handle);
5-6
Cursor Right-9
v_curright(handle);
5-7
Cursor Left-9
vcurleft(handle);
5-8
Home Cursor-9
vcurhome(handle);
5-9
Erase to End of Screen-9
v eeos(handle);
5-10
Erase to End of Line-9
veeol(handle);
5-11
Direct Cursor Address-9
vs_curaddress(handle, row, column);
5-12
Output Cursor Addressable Text-9
v_curtext(handle, 8istring);
5-13
Reverse Video On-9
vrvon(handle);
5-14
Reverse Video Off-9
v_rvoff(handle);
5-15
Inquire Current Alpha Cursor
Address-9
vq_curaddress(handle, 8trow, &column);
5-16
Inquire Tablet Status-9
status=vq_tabstatus(handle);
5-17
Hard Copy-9
v_hardcopy(handle);
5-18
Place Graphic Cursor at
Location-9
v_dspcur(handle, x, y);
5-19
Remove Last Graphic Cursor-9
v_rmcur(handle);
5-20
Form Advance-9
v_form_adv(handle);
5-21
Output Window-9
v_output_window(handle, xyarray);
5-22
Clear Display List-9
vcleardispjist(handle);
5-23
Output Bit Image File-9
v bit_image(handle,filename,aspect,
scaling,num_pts,xyarray);
5-60
Select Palette-9
selected=vs_palette(handle, palette);
5-91
Inquire Palette Film Types-9
vqp films(handle, film names);
5-92
Inquire Palette Driver State-9
vqp_state(handle, 8iport, 8ifilm_name,
tightness, 8«interlace, 8<planes,
8iindexes);
5-93
Set Palette Driver State-9
vsp_state(handle, port, film num,
lightness, interlace, planes,
indexes);
5-94
Save Palette Driver State-9
vsp save(handle);
5-95
Suppress Palette Messages-9
vspmessage(handle);
5-96
Palette Error lnquire-9
status=vqp_error(handle);
5-98
Update Metafile Extents-9
v meta_extents(handle,min_x,min_y,
max_x,max_y);
5-99
Write Metafile Item-9
v_write_meta(handle, numintin,
intin, num ptsin, ptsin);
Op Code
Function Name-Section
Procedure Name
5-100
Change GEM VDI File Name-9
vm filename(handle, filename);
6
Polyline-4
v pline(handle, count, pxyarray);
7
Polymarker-4
v pmarker(handle, count, pxyarray);
8
Text-4
v_gtext(handle, x, y, string);
9
Filled Area-4
v_fillarea(handle, count, pxyarray);
10
Cell Array-4
v_cellarray(handle, pxyarray,
row length, el used, num rows,
wrt mode, colarray);
11
GDPs
11-1
Bar-4
v_bar(handle, pxyarray);
11-2
Arc-4
v_arc(handle, x, y, radius, begang,
endang);
11-3
Pie-4
v pieslice(hand!e, x, y, radius,
begang, endang);
11-4
Circle-4
v_circle(handle, x, y, radius);
11-5
Ellipse-4
v_ellipse(handle, x, y, xradius,
yradius);
11-6
Elliptical Arc-4
v_ellarc(handle, x, y, xradius,
yradius, begang, endang);
11-7
Elliptical Pie-4
v_ellpie(handle, x, y, xradius,
yradius, begang, endang);
11-8
Rounded Rectangle-8
v rbox(handle, xyarray);
11-9
Filled Rounded Rectangle-8
v rfbox(handle, xyarray);
11-10
Justified Graphics Text-8
v_justified(handle, x, y, string,
length, word space, char space);
12
Set Character Height,
Absolute Mode-5
vst_height(handle, height,
8ichar_width, 8<char_height,
8icell_width, 8icell_height);
13
Set Character Baseline Vector-5
set_baseline=vst_rotation(handle,
angle);
14
Set Color Representation-5
vs_color(handle, index, rgbjn);
15
Set Polyline Linetype-5
set type=vsl type(hand!e, style);
16
Set Polyline Line Width-5
set_width=vsl_width(handle, width);
17
Set Polyline Color Index-5
set_color=vsl_color(handle,
colorindex);
18
Set Polymarker Type-5
set_type=vsm_type(handle, symbol);
19
Set Polymarker Height-5
set_height=vsm_height(handle, height);
20
Set Polymarker Color Index-5
set_color=vsm_color(handle, color index);
21 Set Text Face-5
22 Set Graphic Text Color Index-5
23 Set Fill Interior Style-5
Op Code Function Name-Section
24 Set Fill Style Index-5
25 Set Fill Color Index-5
26 Inquire Color Representation-8
27 Inquire Cell Array-8
28 Input Locator, Request Mode-7
28 Input Locator, Sample Mode-7
29 Input Valuator, Request Mode-7
29 Input Valuator, Sample Mode-7
30 Input Choice, Request Mode-7
30 Input Choice, Sample Mode-7
31 Input String, Request Mode-7
31 Input String, Sample Mode-7
32 Set Writing Mode-5
33 Set Input Mode-7
35 Inquire Current Polyline Attributes-8
36 Inquire Current Polylmarker
Attributes-8
37 Inquire Current Fill Area Attributes-8
38 Inquire Current Graphic Text
Attributes-8
39 Set Graphic Text Alignment-5
100 Open Virtual Screen Workstation-1
101
102
Close Virtual Screen Workstation-1
Extended lnquire-8
set_font=vst_font(handle, font);
set_color=vst_color(handle, color index);
set_interior=vsf_interior(handle, style);
Procedure Name
set_style=vsf_style(handle, style index);
set_color=vsf_color(handle, color index);
vq_color(handle, colorjndex,
set_flag, rgb);
vq_cellarray(handle, pxyarray,
rowjength, num_rows, &el_used,
&rows_used, &status, colarray);
vrq_locator(handle, x, y, &xout,
&yout, &term);
status=vsm_locator(handle, x, y,
&xout, &yout, &term);
vrq_valuator(handle, valuatorJn,
&valuator_out, &terminator);
vsm_valuator(handle, valjn,
&val_out, &term, &status);
vrq_choice(handle, chjn, 8(Ch_out);
status=vsm_choice(handle, &choice);
vrq_string(handle, max iength,
echo mode, echo xy, 8<string);
status=vsm_string(handle, max iength,
echo mode, echo_xy, 8istring);
set_mode=vswr_mode(handle, mode);
vsin_mode(handle, dev type, mode);
vql_attributes(handle, attrib);
vqm_attributes(handle, attrib);
vqf_attributes(handle, attrib);
vqt_attributes(handle, attrib);
vst_alignment(handle, hor in,
vert in, &hor_out, &vert out);
v_opnvwk(work_in, &handle,
workout);
v_clsvwk(handle);
vq_extnd(handle, owflag, work out);
103
Contour Fill-4
v_contourfill(handle, x, y, index);
104
Set Fill Perimeter Visibility-5
set_perimeter=vsf_perimeter(handle,
per_vis);
105
Get Pixel-6
v ge^pixeKhandle, x, y, pel, index);
106
Set Graphic Text Special Effects-5
set effect=vst_effects(handle, effect);
Op Code
Function Name-Section
Procedure Name
107
Set Character Cell Height,
Points Mode-5
set point=vst_point(handle, point,
&char_width, 8tchar height,
8tcell_width, 8«cell_height);
108
Set Polyline End Styles-5
vsl_ends(handle, beg style,
endstyle);
109
Copy Raster, Opaque-6
vro cpyfm(handle, wr mode, pxyarray,
srcMFDB, pdesMFDB);
110
Transform Form-6
vr_trn_fm(handle, psrcMFDB, pdesMFDB);
111
Set Mouse Form-6
vsc form(handle, pcur form);
112
Set User-defined Fill Pattern-6
vsf udpat(handle, pfill pat);
113
Set User-defined Line Style-6
vsl_udsty(handle, pattern);
114
Fill Rectangle-6
vr recfl(handle, pxyarray);
115
Inquire Input Mode-8
vqin_mode(handle, dev type, 8tinput_mode);
116
Inquire Text Extent-8
vqt_extent(handle, string, extent);
117
Inquire Character Cell Width-8
status=vqt_width(handle, character,
8tcell_width, 8ileft_delta,
8iright_delta);
118
Exchange Timer Interrupt Vector-7
vex_timv(handle, tim addr,
otim_addr,8itim_conv);
119
Load Fonts-3
additional=vst_load_fonts(handle,
select);
120
Unload Fonts-3
vst_unload_fonts(handle, select);
121
Copy Raster, Transparent-6
vrt_cpyfm(handle, wrmode, pxyarray,
psrcMFDB, pdesMFDB, color index);
122
Show Cursor-6
v show c(handle, reset);
123
Hide Cursor-6
vhidecjhandle);
124
Sample Mouse Button State-7
vq_mouse(handle, 8ipstatus, 8ix, &y);
125
Exchange Button Change Vector-7
vex_butv(handle, pusrcode, psavcode);
126
Exchange Mouse Movement Vector-7
vex_motv(handle, pusrcode, psavcode);
127
Exchange Cursor Change Vector-7
vex_curv(handle, pusrcode, psavcode);
128
Sample Keyboard State
Information-7
vq_key_s(handle, 8ipstatus);
129
Set Clipping Rectangle-3
vs_clip(handle, clip flag, pxyarray);
130
Inquire Face Name and Index-8
index=vqt_name(handle, element num,
name);
131
Inquire Current Face Information-8
vqt_font_info(handle, 8iminADE,
&maxADE, distances, maxwidth,
effects);
Live Music
Archive
Librivox
Free Audio
Metropolitan Museum
Cleveland
Museum of Art
Internet
Arcade
Console Living Room
Open Library
American
Libraries
TV News
Understanding
9/11